Skip to content

Commit 909a214

Browse files
iam-veeramallaiam-veeramalla
authored
Merge pull request #1423 from veeramalla-f5/crddocs
Update CustomResource Documentation
2 parents 65efd69 + d0a8a11 commit 909a214

File tree

11 files changed

+459
-54
lines changed

11 files changed

+459
-54
lines changed

‎docs/_static/config_examples/crd/CustomResource.md‎

Lines changed: 170 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -9,27 +9,143 @@ This page is created to document the behaviour of CIS in CRD Mode(ALPHA Release)
99
* 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.
1010
* 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.
1111

12+
## Contents
13+
* CIS supports 2 Custom Resources at this point of time.
14+
- VirtualServer
15+
- TLSProfile
16+
17+
## VirtualServer
18+
19+
* VirtualServer resource defines load balancing configuration for a domain name.
20+
```
21+
apiVersion: "cis.f5.com/v1"
22+
kind: VirtualServer
23+
metadata:
24+
name: coffee-virtual-server
25+
labels:
26+
f5cr: "true"
27+
spec:
28+
host: coffee.example.com
29+
virtualServerAddress: "172.16.3.4"
30+
pools:
31+
- path: /coffee
32+
service: svc-2
33+
servicePort: 80
34+
```
35+
36+
**Note: The above VirtualServer is insecure, Attach a TLSProfile to make it secure**
37+
38+
## TLSProfile
39+
40+
* TLSProfile is used to specify the TLS termination for a single/list of services in a VirtualServer Custom Resource. TLS termination relies on SNI. Any non-SNI traffic received on port 443 may result in connection issues.
41+
* TLSProfile can be created either with certificates stored as k8s secrets or can be referenced to profiles existing in BIG-IP
42+
43+
```
44+
apiVersion: cis.f5.com/v1
45+
kind: TLSProfile
46+
metadata:
47+
name: reencrypt-tls
48+
labels:
49+
f5cr: "true"
50+
spec:
51+
tls:
52+
termination: reencrypt
53+
clientSSL: /common/clientssl
54+
serverSSL: /common/serverssl
55+
reference: bigip # --> reference profiles created in BIG-IP by User
56+
hosts:
57+
- coffee.example.com
58+
```
59+
60+
## VirtualServer with TLSProfile
61+
62+
* VirtualServer with TLSProfile is used to specify the TLS termination. TLS termination relies on SNI. Any non-SNI traffic received on port 443 may result in connection issues. Below example shows how to attach a TLSProfile to a VirtualServer.
63+
64+
```
65+
apiVersion: cis.f5.com/v1
66+
kind: VirtualServer
67+
metadata:
68+
name: coffee-virtual-server
69+
labels:
70+
f5cr: "true"
71+
namespace: default
72+
spec:
73+
host: coffee.example.com
74+
tlsProfileName: reencrypt-tls. # --> This will attach reencrypt-tls TLSProfile
75+
virtualServerAddress: "172.16.3.4"
76+
pools:
77+
- path: /coffee
78+
service: svc
79+
servicePort: 80
80+
```
81+
82+
* CIS has a 1:1 mapping for a domain(CommonName) and BIG-IP-VirtualServer.
83+
* User can create any number of custom resources for a single domain. For example, User is flexible to create 2 VirtualServers with
84+
different terminations(for same domain), one with edge and another with re-encrypt. Todo this he needs to create two VirtualServers one with edge TLSProfile and another with re-encrypt TLSProfile.
85+
- Both the VirutalServers should be created with same virtualServerAddress
86+
* Single or Group of VirtualServers(with same virtualServerAddress) will be created as one common BIG-IP-VirtualServer.
87+
1288
## How CIS works with CRDs
1389

14-
* CIS registers to the kubernetes client-go using informers to retrieve Virtual Server, Service, Endpoint and Node creation, updation and deletion events. Resources identified from such events
15-
will be pushed to a Resource Queue maintained by CIS.
90+
* CIS registers to the kubernetes client-go using informers to retrieve Virtual Server, TLSProfile, Service, Endpoint and Node creation, updation and deletion events. Resources identified from such events will be pushed to a Resource Queue maintained by CIS.
1691
* Resource Queue holds the resources to be processed.
17-
* Virtual Server is the Primary citizen. Any changes in Service, Endpoint, Node will indirectly affect Virtual Server.
18-
* Worker fetches the affected Virtual Servers from Resource Queue to populate a common structure which holds the configuration of all the Virtual Servers such as Virtual Server IP, Pool Members and L7 LTM policy actions.
92+
* Virtual Server is the Primary citizen. Any changes in TLSProfile, Service, Endpoint, Node will process their affected Virtual Servers. For Example, If svc-a is part of foo-VirtualServer and bar-VirtualServer, Any changes in svc-a will put foo-VirtualServer and bar-VirtualServer in resource queue.
93+
* Worker fetches the affected Virtual Servers from Resource Queue to populate a common structure which holds the configuration of all the Virtual Servers such as TLSProfile, Virtual Server IP, Pool Members and L7 LTM policy actions.
1994
* Vxlan Manager prepares the BIG-IP NET configuration as AS3 cannot process FDB and ARP entries.
2095
* LTM Configuration(using AS3) and NET Configuration(using CCCL) will be created in CIS Managed Partition defined by the User.
2196

22-
## Alpha Release
23-
**Supported Features**
2497

25-
* Supports Custom Resource type: VirtualServer.
26-
* Responds to changes in VirtualServer resources.
27-
* Responds to changes in Services and Endpoints.
28-
* Creates a common partition in BIG-IP for both LTM and NET objects.
98+
**Content**
99+
100+
# VirtualServer
101+
* Schema Validation
102+
- OpenAPI Schema Validation
103+
https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/master/docs/_static/config_examples/crd/basic/vs-customresourcedefinitions.yml
29104

30-
**To Be Implemented**
31105

32-
* TLS support for Virtual Server Custom Resource.
106+
**VirtualServer Components**
107+
108+
| PARAMETER | TYPE | REQUIRED | DEFAULT | DESCRIPTION |
109+
| ------ | ------ | ------ | ------ | ------ |
110+
| host | String | required | NA | Virtual Host |
111+
| pools | List of pool | required | NA | List of BIG-IP Pool members |
112+
| virtualServerAddress | String | required | NA | IP Address of BIG-IP Virtual Server |
113+
| TLSProfile | String | optional | NA | Describes the TLS configuration for BIG-IP Virtual Server |
114+
115+
**Pool Components**
116+
117+
| PARAMETER | TYPE | REQUIRED | DEFAULT | DESCRIPTION |
118+
| ------ | ------ | ------ | ------ | ------ |
119+
| path | String | required | NA | Path to access the service |
120+
| service | String | required | NA | Service deployed in kubernetes cluster |
121+
| 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 |
122+
| servicePort | String | required | NA | Port to access Service |
123+
| monitor | String | Optional | NA | Health Monitor to check the health of Pool Members |
124+
125+
**Health Monitor**
126+
127+
| PARAMETER | TYPE | REQUIRED | DEFAULT | DESCRIPTION |
128+
| ------ | ------ | ------ | ------ | ------ |
129+
| type | String | required | NA | http or https |
130+
| send | String | optional | “GET /rn” | HTTP request string to send. |
131+
| recv | String | optional | NA | String or RegEx pattern to match in first 5,120 bytes of backend response. |
132+
| interval | Int | required | 5 | Seconds between health queries |
133+
| timeout | Int | Optional | 16 | Seconds before query fails |
134+
135+
## TLSProfile
136+
* Schema Validation
137+
- OpenAPI Schema Validation
138+
https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/master/docs/_static/config_examples/crd/tls/tls-customresourcedefinitions.yml
139+
140+
141+
**TLSProfile Components**
142+
143+
| PARAMETER | TYPE | REQUIRED | DEFAULT | DESCRIPTION |
144+
| ------ | ------ | ------ | ------ | ------ |
145+
| termination | String | required | NA | Termination on BIG-IP Virtual Server. Allowed options are [edge, reencrypt, passthrough] |
146+
| clientSSL | String | required | NA | ClientSSL Profile on the BIG-IP. Example /Common/clientssl |
147+
| serverSSL | String | optional | NA | ServerSSL Profile on the BIG-IP. Example /Common/serverssl |
148+
| reference | String | required | NA | Describes the location of profile, BIG-IP or k8s Secrets. We currently support BIG-IP profiles only |
33149

34150
## Prerequisites
35151
Since CIS is using the AS3 declarative API we need the AS3 extension installed on BIG-IP. Follow the link to install AS3 3.18 is required for CIS 2.0.
@@ -39,62 +155,62 @@ Since CIS is using the AS3 declarative API we need the AS3 extension installed o
39155
## Installation
40156
**Create CIS Controller, BIG-IP Credentials and RBAC Authentication**
41157

42-
* BIG-IP Credentials
158+
* Install F5 CRDs
159+
- Download the below file and execute the command as shown.
160+
161+
https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/master/docs/_static/config_examples/crd/Install/customresourcedefinitions.yml
162+
```sh
163+
kubectl create -f customresourcedefinitions.yml [-n kube-system]
164+
```
165+
166+
* Create BIG-IP Credentials
43167
```sh
44168
kubectl create secret generic bigip-login -n kube-system --from-literal=username=admin --from-literal=password=dummy
45169
```
46170
* Create Service Account
47171
```sh
48-
kubectl create serviceaccount k8s-bigip-ctlr -n kube-system
172+
kubectl create serviceaccount bigip-ctlr [-n kube-system]
49173
```
50174
* Create Cluster Role and Cluster Role Binding
51-
```
52-
# for reference only
53-
# Should be improved as per your cluster requirements
54-
kind: ClusterRole
55-
apiVersion: rbac.authorization.k8s.io/v1
56-
metadata:
57-
name: bigip-ctlr-clusterrole
58-
rules:
59-
- apiGroups: ["", "extensions"]
60-
resources: ["nodes", "services", "endpoints", "namespaces", "ingresses", "pods"]
61-
verbs: ["get", "list", "watch"]
62-
- apiGroups: ["", "extensions"]
63-
resources: ["configmaps", "events", "ingresses/status"]
64-
verbs: ["get", "list", "watch", "update", "create", "patch"]
65-
- apiGroups: ["cis.f5.com"]
66-
resources: ["virtualservers"]
67-
verbs: ["get", "list", "watch", "update"]
68-
- apiGroups: ["", "extensions"]
69-
resources: ["secrets"]
70-
resourceNames: ["<secret-containing-bigip-login>"]
71-
verbs: ["get", "list", "watch"]
72-
---
73-
74-
kind: ClusterRoleBinding
75-
apiVersion: rbac.authorization.k8s.io/v1
76-
metadata:
77-
name: bigip-ctlr-clusterrole-binding
78-
namespace: <controller_namespace>
79-
roleRef:
80-
apiGroup: rbac.authorization.k8s.io
81-
kind: ClusterRole
82-
name: bigip-ctlr-clusterrole
83-
subjects:
84-
- apiGroup: ""
85-
kind: ServiceAccount
86-
name: bigip-ctlr
87-
namespace: <controller_namespace>
175+
- Download the below file and execute the command as shown.
176+
177+
https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/master/docs/_static/config_examples/crd/Install/clusterrole.yml
178+
```sh
179+
kubectl create -f clusterrole.yml [-n kube-system]
88180
```
89181

90182
**Supported Controller Modes: NodePort and Cluster**
91183
* [CIS Architecture](https://clouddocs.f5.com/containers/v2/kubernetes/kctlr-modes.html)
92184

185+
* Deploy k8s-bigip-ctlr in nodeport and customresource mode.
186+
- Download the below file and execute the command as shown.
187+
188+
https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/master/docs/_static/config_examples/crd/Install/sample-nodeport-k8s-bigip-ctlr-crd-secret.yml
189+
```sh
190+
kubectl create -f sample-nodeport-k8s-bigip-ctlr-crd-secret.yml [-n kube-system]
191+
```
192+
193+
## Cluster Mode
93194
**Add BIG-IP device to VXLAN**
94195
* [Overview of CIS VXLAN](https://clouddocs.f5.com/containers/v2/kubernetes/flannel-bigip-info.html)
95196
* [Configure VXLAN with CIS](https://clouddocs.f5.com/containers/v2/kubernetes/kctlr-use-bigip-k8s.html)
96197

97-
**Sample Configuration for reference**
98-
* https://github.com/F5Networks/k8s-bigip-ctlr/tree/master/docs/_static/config_examples/crd/basic
198+
* Deploy k8s-bigip-ctlr in cluster and customresource mode.
199+
- Download the below file and execute the command as shown.
200+
201+
https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/master/docs/_static/config_examples/crd/Install/sample-cluster-k8s-bigip-ctlr-crd-secret.yml
202+
```sh
203+
kubectl create -f sample-cluster-k8s-bigip-ctlr-crd-secret.yml [-n kube-system]
204+
```
99205

100-
**Note**:: “--custom-resource-mode=true” deploys CIS in Custom Resource Mode.
206+
## To Be Implemented
207+
* TLSProfile Support with k8s secrets
208+
* A/B Deployment
209+
* Support for WAF
210+
* Rewrite Rules
211+
* ErrorPage
212+
213+
## Note
214+
* “--custom-resource-mode=true” deploys CIS in Custom Resource Mode.
215+
* CIS does not watch for ingress/routes when deployed in CRD Mode.
216+
* CIS does not support combination of CRDs with any of Ingress/Routes or Configmaps.

‎docs/_static/config_examples/crd/Install/clusterrole.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# for reference only
2+
# Should be changed as per your cluster requirements
3+
kind: ClusterRole
4+
apiVersion: rbac.authorization.k8s.io/v1
5+
metadata:
6+
name: bigip-ctlr-clusterrole
7+
rules:
8+
- apiGroups: ["", "extensions"]
9+
resources: ["nodes", "services", "endpoints", "namespaces", "ingresses", "pods"]
10+
verbs: ["get", "list", "watch"]
11+
- apiGroups: ["", "extensions"]
12+
resources: ["configmaps", "events", "ingresses/status"]
13+
verbs: ["get", "list", "watch", "update", "create", "patch"]
14+
- apiGroups: ["cis.f5.com"]
15+
resources: ["virtualservers", "tlsprofiles"]
16+
verbs: ["get", "list", "watch", "update"]
17+
- apiGroups: ["", "extensions"]
18+
resources: ["secrets"]
19+
resourceNames: ["<secret-containing-bigip-login>"]
20+
verbs: ["get", "list", "watch"]
21+
---
22+
23+
kind: ClusterRoleBinding
24+
apiVersion: rbac.authorization.k8s.io/v1
25+
metadata:
26+
name: bigip-ctlr-clusterrole-binding
27+
namespace: <controller_namespace>
28+
roleRef:
29+
apiGroup: rbac.authorization.k8s.io
30+
kind: ClusterRole
31+
name: bigip-ctlr-clusterrole
32+
subjects:
33+
- apiGroup: ""
34+
kind: ServiceAccount
35+
name: bigip-ctlr
36+
namespace: <controller_namespace>

0 commit comments

Comments
 (0)