From 2e5a4c95a1b16384815f4024364876f1d72b441b Mon Sep 17 00:00:00 2001 From: myf5 Date: Wed, 26 Jul 2023 15:24:58 +0800 Subject: [PATCH] reconstruct the site to reflect the big-ip next integration --- docs/.DS_Store | Bin 6148 -> 6148 bytes docs/Design/{index.md => bip.md} | 0 docs/Design/bipnext.md | 43 +++++ docs/Use-Cases/grpc-routing.md | 3 + docs/Use-Cases/http-redirect-rewrite.md | 94 +++++++++++ docs/Use-Cases/http-routing.md | 161 ++++++++++++++++++ docs/Use-Cases/multiple-ns.md | 3 + docs/Use-Cases/service-definition.md | 208 ++++++++++++++++++++++++ docs/Use-Cases/simple-gateway.md | 107 ++++++++++++ docs/Use-Cases/tcp.md | 3 + docs/Use-Cases/tls.md | 3 + docs/Use-Cases/traffic-splitting.md | 55 +++++++ docs/guides-next/getstarted.md | 7 + docs/index.md | 2 + docs/quick-start/index.md | 152 +++++++++++++++++ docs/quick-start/installation.md | 29 ++++ docs/quick-start/parameters.md | 165 +++++++++++++++++++ docs/quick-start/uninstall.md | 11 ++ mkdocs.yml | 9 +- 19 files changed, 1053 insertions(+), 2 deletions(-) rename docs/Design/{index.md => bip.md} (100%) create mode 100644 docs/Design/bipnext.md create mode 100644 docs/Use-Cases/grpc-routing.md create mode 100644 docs/Use-Cases/http-redirect-rewrite.md create mode 100644 docs/Use-Cases/http-routing.md create mode 100644 docs/Use-Cases/multiple-ns.md create mode 100644 docs/Use-Cases/service-definition.md create mode 100644 docs/Use-Cases/simple-gateway.md create mode 100644 docs/Use-Cases/tcp.md create mode 100644 docs/Use-Cases/tls.md create mode 100644 docs/Use-Cases/traffic-splitting.md create mode 100644 docs/guides-next/getstarted.md create mode 100644 docs/quick-start/index.md create mode 100644 docs/quick-start/installation.md create mode 100644 docs/quick-start/parameters.md create mode 100644 docs/quick-start/uninstall.md diff --git a/docs/.DS_Store b/docs/.DS_Store index a7047b1b1ea249eb4d17d4ee0441658c63bbbd40..1b1b41f2a8f19a42828771d2f4b6d3af4a619848 100644 GIT binary patch delta 195 zcmZoMXfc@J&&akhU^gQp+hiW5fA!o9=?tX|nG7imsSL#ox(satuWaCtwf}&atzw&|%h%+_|GDom%X6N|J4*&sK BEjIuF delta 33 pcmZoMXfc@J&&aefU^nAr0}+ experimental in v0.5.1 + # type: ReplaceFullPath + # replaceFullPath: /fake + port: 443 + statusCode: 301 + backendRefs: + - name: tea + port: 80 +``` + +In this `HTTPRoute` configuration, when we access `http://gateway.test.automation`, the traffic will be redirect to `https://www.example.com/`: + +```shell +$ curl 10.250.18.119 -H "Host: gateway.test.automation" -v +* Trying 10.250.18.119:80... +* Connected to 10.250.18.119 (10.250.18.119) port 80 (#0) +> GET / HTTP/1.1 +> Host: gateway.test.automation +> User-Agent: curl/7.79.1 +> Accept: */* +> +* Mark bundle as not supporting multiuse +* HTTP 1.0, assume close after body +< HTTP/1.0 301 Moved Permanently +< Location: https://www.example.com:443/ +< Server: BigIP +* HTTP/1.0 connection set to keep alive! +< Connection: Keep-Alive +< Content-Length: 0 +< +* Connection #0 to host 10.250.18.119 left intact +``` + +As shown here, the virtual responses `< HTTP/1.0 301 Moved Permanently`. + +### Rewrites + +*Experimental in gateway api v0.5.1, will be supported in future.* + +```yaml +# --- + +# apiVersion: gateway.networking.k8s.io/v1beta1 +# kind: HTTPRoute +# metadata: +# name: test-filter-urlrewrite +# spec: +# parentRefs: +# - name: gateway +# sectionName: http +# hostnames: +# - "cafe.example.com" +# rules: +# - filters: +# - type: URLRewrite +# urlRewrite: +# hostname: www.example.com +# path: +# type: ReplaceFullPath +# replaceFullPath: /fake +# backendRefs: +# - name: tea +# port: 80 +``` \ No newline at end of file diff --git a/docs/Use-Cases/http-routing.md b/docs/Use-Cases/http-routing.md new file mode 100644 index 0000000..b02ad0f --- /dev/null +++ b/docs/Use-Cases/http-routing.md @@ -0,0 +1,161 @@ +## HTTP Routing + +In this scenario, based on [Simple Gateway](./simple-gateway.md), we demonstrate the process of binding multiple httproutes in one gateway to forward traffic with different characteristics, to different backend servers. + +In this page, we ignore the configuration of `GatewayClass` and `Gateway`, and directly show the configurations of different `HTTPRoute` resources. + +### Request header based matching + +```yaml +--- + +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: HTTPRoute +metadata: + name: test-match-header +spec: + parentRefs: + - name: gateway + sectionName: http + hostnames: + - gateway.test.automation + rules: + - matches: + - headers: + - name: test + value: automation + backendRefs: + - name: test-service + port: 80 +``` + +When the domain name of the request is `gateway.test.automation` and the request header contains `test == automation`, the traffic is forwarded to the `test-service` service with port 80. + +### Request method based matching + +```yaml +--- + +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: HTTPRoute +metadata: + name: test-match-method +spec: + parentRefs: + - name: gateway + sectionName: http + hostnames: + - gateway.test.automation + rules: + - matches: + - method: GET + - method: OPTIONS + backendRefs: + - name: test-service + port: 80 +``` + +When the domain name is `gateway.test.automation` and the request method is `GET` or `OPTIONS`, the request is forwarded to the `test-service` service with port 80. + +### Request path based matching + +```yaml +--- + +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: HTTPRoute +metadata: + name: test-match-path +spec: + parentRefs: + - name: gateway + sectionName: http + hostnames: + - gateway.test.automation + rules: + - matches: + - path: + type: PathPrefix + value: /path-test + backendRefs: + - name: test-service + port: 80 +``` + +When the request domain name is `gateway.test.automation` and the request path is `/path-test`, the request is forwarded to the `test-service` service with port 80. + +### Request parameter based matching + +```yaml +--- + +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: HTTPRoute +metadata: + name: test-query-params +spec: + parentRefs: + - name: gateway + sectionName: http + hostnames: + - gateway.test.automation + rules: + - matches: + - queryParams: + - name: test + value: automation + backendRefs: + - name: test-service + port: 80 +``` + +When the request domain name is `gateway.test.automation`, and the request parameters contain `?test=automation`, the request is forwarded to the `test-service` service with port 80. + +### Multiple matches in a HTTPRoute + +```yaml +--- + +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: HTTPRoute +metadata: + name: test-multiple-rules +spec: + parentRefs: + - name: gateway + sectionName: http + hostnames: + - gateway.test.automation + rules: + - matches: + - queryParams: + - name: test + value: automation + path: + type: PathPrefix + value: /path-test + backendRefs: + - name: test-service1 + port: 80 + - matches: + - queryParams: + - name: test + value: automation + - path: + type: PathPrefix + value: /path-test + backendRefs: + - name: test-service2 + port: 80 + - backendRefs: + - name: test-service3 + port: 80 +``` + +When the request domain name is `gateway.test.automation`, and + +* If the path of the request is `/path-test`, **AND** the request parameters contain `?test=automation`, the request will be forwarded to the `test-service1` service, port 80. + +* If the path of the request is `/path-test`, **OR** the request parameters contain `?test=automation`, *(only one of the 2 conditions)*, the request will be forwarded to the `test-service2` service, port 80. + +* In other cases, it is forwarded to the `test-service3` service, port 80. \ No newline at end of file diff --git a/docs/Use-Cases/multiple-ns.md b/docs/Use-Cases/multiple-ns.md new file mode 100644 index 0000000..063296e --- /dev/null +++ b/docs/Use-Cases/multiple-ns.md @@ -0,0 +1,3 @@ +## Cross-Namespace routing + +*Supported from bigip-kubernetes-gateway v0.0.5.* \ No newline at end of file diff --git a/docs/Use-Cases/service-definition.md b/docs/Use-Cases/service-definition.md new file mode 100644 index 0000000..c404a1a --- /dev/null +++ b/docs/Use-Cases/service-definition.md @@ -0,0 +1,208 @@ + +*The servcie definitions for references only* + +Note that: + +`tea` servcie is defined as `NodePort` and `coffee` service is `ClusterIP`. Change it as necessary. + +## tea.yaml +```yaml + +--- + +apiVersion: apps/v1 +kind: Deployment +metadata: + name: tea +spec: + replicas: 1 + selector: + matchLabels: + app: tea + template: + metadata: + labels: + app: tea + spec: + containers: + - name: tea + image: nginx:latest + ports: + - containerPort: 80 + volumeMounts: + - name: config-volume + mountPath: /etc/nginx/nginx.conf + subPath: nginx.conf + - name: config-volume + mountPath: /etc/nginx/njs/dumps.js + subPath: dumps.js + volumes: + - name: config-volume + configMap: + name: nginx-config-tea + +--- + +apiVersion: v1 +kind: Service +metadata: + name: tea +spec: + type: NodePort + ports: + - port: 80 + targetPort: 80 + protocol: TCP + name: http + selector: + app: tea + +--- + +apiVersion: v1 +kind: ConfigMap +metadata: + name: nginx-config-tea +data: + nginx.conf: | + user nginx; + worker_processes 1; + + load_module modules/ngx_http_js_module.so; + + events { + worker_connections 1024; + } + + http { + js_import njs/dumps.js; + server { + listen 80; + server_name localhost; + + location / { + js_content dumps.hello; + } + } + } + dumps.js: | + function hello(r) { + let d = { + 'queries': r.args, + 'headers': r.headersIn, + 'version': r.httpVersion, + 'method': r.method, + 'remote-address': r.remoteAddress, + 'body': r.requestText, + 'uri': r.uri, + 'server_name': "TEA" + } + + r.return(200, JSON.stringify(d)+"\n"); + } + + export default {hello}; + + +``` + +## coffee.yaml + +```yaml +--- + +apiVersion: apps/v1 +kind: Deployment +metadata: + name: coffee +spec: + replicas: 1 + selector: + matchLabels: + app: coffee + template: + metadata: + labels: + app: coffee + spec: + containers: + - name: coffee + image: nginx:latest + ports: + - containerPort: 80 + volumeMounts: + - name: config-volume + mountPath: /etc/nginx/nginx.conf + subPath: nginx.conf + - name: config-volume + mountPath: /etc/nginx/njs/dumps.js + subPath: dumps.js + volumes: + - name: config-volume + configMap: + name: nginx-config-coffee + +--- + +apiVersion: v1 +kind: Service +metadata: + name: coffee +spec: + type: ClusterIP + ports: + - port: 80 + targetPort: 80 + protocol: TCP + name: http + selector: + app: coffee + +--- + +apiVersion: v1 +kind: ConfigMap +metadata: + name: nginx-config-coffee +data: + nginx.conf: | + user nginx; + worker_processes 1; + + load_module modules/ngx_http_js_module.so; + + events { + worker_connections 1024; + } + + http { + js_import njs/dumps.js; + server { + listen 80; + server_name localhost; + + location / { + js_content dumps.hello; + } + } + } + dumps.js: | + function hello(r) { + let d = { + 'queries': r.args, + 'headers': r.headersIn, + 'version': r.httpVersion, + 'method': r.method, + 'remote-address': r.remoteAddress, + 'body': r.requestText, + 'uri': r.uri, + 'server_name': "COFFEE" + } + + r.return(200, JSON.stringify(d)+"\n"); + } + + export default {hello}; + + +``` \ No newline at end of file diff --git a/docs/Use-Cases/simple-gateway.md b/docs/Use-Cases/simple-gateway.md new file mode 100644 index 0000000..29d8051 --- /dev/null +++ b/docs/Use-Cases/simple-gateway.md @@ -0,0 +1,107 @@ +## Deploying a simple Gateway + +Just like the official website describes [here](https://gateway-api.sigs.k8s.io/guides/simple-gateway/){:target="_blank"}, a `Gateway` can be deployed as an ingress. In this page, we provide another version of a simple gateway deployment. + +In this usecase, we will have a preliminary understanding of the definition methods of `HTTPRoute` and related resources, and understand how `HTTPRoute` achieves the routing and forwarding capability of requests. + +To demo this simple HTTPRoute usecase, we will create an `HTTPRoute` resource that defines traffic forwarding rules, and we need to create the `GatewayClass` and `Gateway` resource on which it depends. To demonstrate the effect, we also need to create a `Service` resource. + +When we access the ingress IP defined in the `Gateway`, the traffic is forwarded to the backend service by the rule defined in `HTTPRoute`. + +gatewayclass.yaml +```yaml +--- + +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: GatewayClass +metadata: + name: bigip +spec: + controllerName: f5.io/gateway-controller-name + +``` + +gateway.yaml +```yaml +--- + +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: Gateway +metadata: + name: mygateway + labels: + domain: k8s-gateway +spec: + gatewayClassName: bigip + listeners: + - name: http + port: 80 + protocol: HTTP + addresses: + - value: 10.250.17.120 + +``` + +httproute.yaml +```yaml + +--- + +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: HTTPRoute +metadata: + name: myhttproute +spec: + parentRefs: + - name: mygateway + sectionName: http + hostnames: + - gateway.test.automation + rules: + - matches: + - path: + type: PathPrefix + value: /test + headers: + - name: svc + value: coffee + filters: + - type: RequestHeaderModifier + requestHeaderModifier: + add: + - name: tester + value: f5 + backendRefs: + - name: coffee + port: 80 +``` + +*Refer [here](./service-definition.md) for `coffee` definition.* + +In the above demo, the rules in `httproute.yaml` contains two parts: `matches` and `filters`, `matches` defines route matching rules, and `filters` defines the customization process for requests. + +* matches: /test path also contains svc==coffee in the header +* filters: Add a new header tester = f5 + +therefore, + +```shell + +$ curl 10.250.17.120/test -H "Host: gateway.test.automation" -H "svc: coffee" + +{ + "queries": {}, + "headers": { + "Host": "gateway.test.automation", + "User-Agent": "curl/7.79.1","Accept":"*/*", + "svc": "coffee", + "tester": "f5" + }, + "version": "1.1", + "method": "GET", + "remote-address": "10.42.7.0", + "uri": "/test", + "server_name": "COFFEE" +} + +``` \ No newline at end of file diff --git a/docs/Use-Cases/tcp.md b/docs/Use-Cases/tcp.md new file mode 100644 index 0000000..f342b9e --- /dev/null +++ b/docs/Use-Cases/tcp.md @@ -0,0 +1,3 @@ +## TCP routing + +*Experimental in gateway api v0.5.1, will be supported in future.* \ No newline at end of file diff --git a/docs/Use-Cases/tls.md b/docs/Use-Cases/tls.md new file mode 100644 index 0000000..3c5c88e --- /dev/null +++ b/docs/Use-Cases/tls.md @@ -0,0 +1,3 @@ +## TLS Configuration + +*Experimental in gateway api v0.5.1, will be supported in future.* \ No newline at end of file diff --git a/docs/Use-Cases/traffic-splitting.md b/docs/Use-Cases/traffic-splitting.md new file mode 100644 index 0000000..5b7526e --- /dev/null +++ b/docs/Use-Cases/traffic-splitting.md @@ -0,0 +1,55 @@ +## HTTP traffic splitting + +In this usecase, we will understand the slightly more complex application method of `HTTPRoute`. + +You can implement the grayscale publishing of the application through `HTTPRoute`, and smoothly transition traffic to new services. + +See [here](./simple-gateway.md) for `GatwayClass` and `Gateway` definitions. + +```yaml +--- + +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: HTTPRoute +metadata: + name: myhttproute +spec: + parentRefs: + - name: mygateway + sectionName: http + hostnames: + - gateway.test.automation + rules: + - matches: + - path: + type: PathPrefix + value: /test1 + backendRefs: + - name: coffee + port: 80 + weight: 1 + - name: tea + port: 80 + weight: 9 + - matches: + - path: + type: PathPrefix + value: /test2 + backendRefs: + - name: coffee + port: 80 + weight: 9 + - name: tea + port: 80 + weight: 1 +``` + + +*Refer [here](./service-definition.md) for services `tea` and `coffee` definition.* + +In the above `httproute` definition, we see that there are two rules: + +* when we access **/test1**, 90% of the traffic is forwarded to the **tea** service +* when we access **/test2**, 90% of the traffic is forwarded to the **coffee** service + +You may change the two ratios, and run `kubectl apply -f httproute.yaml` again to achieve a change in the traffic ratio. \ No newline at end of file diff --git a/docs/guides-next/getstarted.md b/docs/guides-next/getstarted.md new file mode 100644 index 0000000..92fe356 --- /dev/null +++ b/docs/guides-next/getstarted.md @@ -0,0 +1,7 @@ +# Getting started with BIG-IP Next Kubernetes Gateway Controller + + + +TODO + +We are actively work on this. Will update. diff --git a/docs/index.md b/docs/index.md index cba4138..4da1ace 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,6 +8,8 @@ This is the online docs of F5 BIG-IP kubernetes GatewayAPI Controller. F5 BIG-IP kubernetes GatewayAPI Controller is an [implementation](https://gateway-api.sigs.k8s.io/implementations/){:target="_blank"} of [K8S Gateway API](https://gateway-api.sigs.k8s.io/){:target="_blank"} at [v0.6.2](https://github.com/kubernetes-sigs/gateway-api/releases/tag/v0.6.2){:target="_blank"}. +As F5 has two traffic management system, one is the BIG-IP, the other one is the Next-Generation BIG-IP Software. So we have 2 integration as well. According to the context, if we emphasize the 'Next', that means it is only for BIG-IP Next, otherwise they are same for BIG-IP or BIG-IP Next. + For a list of supported GatewayAPI resources and features, see the [Gateway API Compatibility](https://github.com/f5devcentral/bigip-kubernetes-gateway/blob/master/docs/gateway-api-compatibility.md){:target="_blank"} doc. Check [here](https://github.com/kubernetes-sigs/gateway-api#status){:target="_blank"} for Gateway API's latest status. It's open-source and community supported. Source code repository: [https://github.com/f5devcentral/bigip-kubernetes-gateway](https://github.com/f5devcentral/bigip-kubernetes-gateway){:target="_blank"}. diff --git a/docs/quick-start/index.md b/docs/quick-start/index.md new file mode 100644 index 0000000..c05295e --- /dev/null +++ b/docs/quick-start/index.md @@ -0,0 +1,152 @@ +# Get Started + +You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind){:target="_blank"} to get a local cluster for testing, or run against a remote cluster. + +**Note:** bigip-kubernetes-gateway controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows). If the controller runs in In-Cluster mode, it will depends on the serviceaccount and role/role-binding described in [installation](./installation.md). + +## Kubernetes Setup For Gateway API Integration + +After you have a K8s cluster, we need to configure it for different CNI types to make sure connection between BIG-IP and kubernetes cluster is OK. + +**Note:** + +*To enable Gateway API integration via BIG-IP, actually, we need to configure both sides of BIG-IPs and the Kubernetes cluster, however, the BIG-IP side is configured by controller itself automatically when the controller is started.* + +*Here, we only need to configure Kubernetes side manually. For different CNIs, we have different configuration steps as following.* + +### In Flannel mode + +In flannel network mode, we need to create a BIG-IP virtual node to connect the BIG-IP node to the Kubernetes. + +In the following configuration sample, we use: + +* BIG-IP traffic IP(Flannel VXLAN SelfIP): *`10.250.18.105`* +* BIG-IP traffic Mac(Flannel VXLAN Tunnel MAC): *`fa:16:3e:d5:28:07`* *(see below for the way to get it)* +* podCIDR(BIGIP Flannel Subnet): *`10.42.20.0/24`* *(see below for how to determine it)* + +-> Create and edit the following yaml configuration file `bigip1.yaml`: + +bigip1.yaml: +```yaml +apiVersion: v1 +kind: Node +metadata: + name: bigip1 +annotations: + # Replace IP with Self-IP for your deployment + flannel.alpha.coreos.com/public-ip: "10.250.18.105" + # uncomment the following line if using v6 tunnel and modify bigip v6 address + # flannel.alpha.coreos.com/public-ipv6: "2021:15::125" + # Replace MAC with your BIGIP Flannel VXLAN Tunnel MAC + flannel.alpha.coreos.com/backend-data: '{"VtepMAC":"fa:16:3e:d5:28:07"}' + # uncomment the following line if using v6 tunnel and modify mac accordingly + # flannel.alpha.coreos.com/backend-v6-data: '{"VtepMAC":"fa:16:3e:d5:28:07"}' + flannel.alpha.coreos.com/backend-type: "vxlan" + flannel.alpha.coreos.com/kube-subnet-manager: "true" +spec: + # Replace Subnet with your BIGIP Flannel Subnet + podCIDR: "10.42.20.0/24" + # uncomment the following 3 lines if using v6 tunnel and modify CIDRs using real data + #podCIDRs: + #- "10.42.20.0/24" + #- "2021:118:2:2::/64" +``` + +The mac address `VtepMAC` can be obtained using the TMSH command on BIG-IP: + +`$ show net tunnels tunnel fl-tunnel all-properties` + +`$ show net tunnels tunnel fl-tunnel6 all-properties` + +The pod CIDR `podCIDR` varies and should not be duplicated with the kubernetes cluster's pod CIDRs, see it by: + +`kubectl get node -o yaml | grep podCIDR` + +-> Execute `kubectl apply -f bigip1.yaml` command to create the above virtual node. + +### In Calico mode + +In calico mode, we need to peer BIG-IP(s) as the BGP neighbors of Kubernetes nodes. + +In the following configuration sample, we use: + +* AS(Autonomous System): *`64512`* +* BIG-IP traffic IP: *`10.250.17.111`* + +On master node, + +-> Run the command to get `calicoctl` command line: + +```shell +$ curl -O -L https://github.com/projectcalico/calicoctl/releases/download/v3.10.0/calicoctl` +$ chmod +x calicoctl +$ sudo mv calicoctl /usr/local/bin +``` + +-> Edit `/etc/calico/calico.ctl.cfg` file + +```shell +$ sudo mkdir /etc/calico +$ vim /etc/calico/calicoctl.cfg +``` + +calicoctl.cfg +```yaml +apiVersion: projectcalico.org/v3 +kind: CalicoAPIConfig +metadata: +spec: + datastoreType: "kubernetes" + kubeconfig: "/root/.kube/config" # change to actual kubeconfig path +``` + +-> Run `calicoctl get nodes` to verify calicoctl runtime works OK. + +-> Run the following command to create BGP Group: + +```shell + +cat << EOF | calicoctl create -f - +apiVersion: projectcalico.org/v3 +kind: BGPConfiguration +metadata: + name: default +spec: + logSeverityScreen: Info + nodeToNodeMeshEnabled: true + asNumber: 64512 +EOF +``` + +-> Run the following command to create BIG-IP peer for the kubernetes cluster. + +**Notes**: *Change the peerIP to actual BIG-IP traffic IP(the selfIP for data traffic).* + +```shell +cat << EOF | calicoctl create -f - +apiVersion: projectcalico.org/v3 +kind: BGPPeer +metadata: + name: bgppeer-bigip1 +spec: + peerIP: 10.250.17.111 + asNumber: 64512 +EOF +``` + +-> After the configuration, we can use `calicoctl node status` command to check the BIG-IP peer status: + +```shell +$ calicoctl node status +Calico process is running. + +IPv4 BGP status ++---------------+-------------------+-------+----------+-------------+ +| PEER ADDRESS | PEER TYPE | STATE | SINCE | INFO | ++---------------+-------------------+-------+----------+-------------+ +| 10.250.17.182 | node-to-node mesh | up | 03:07:33 | Established | +| 10.250.17.111 | global | up | 06:18:28 | Established | ++---------------+-------------------+-------+----------+-------------+ +``` + +More references, see https://f5-k8s-istio-lab.readthedocs.io/en/latest/BGP/introduction.html \ No newline at end of file diff --git a/docs/quick-start/installation.md b/docs/quick-start/installation.md new file mode 100644 index 0000000..574106b --- /dev/null +++ b/docs/quick-start/installation.md @@ -0,0 +1,29 @@ +# Installation + +In the code [repository](https://github.com/f5devcentral/bigip-kubernetes-gateway/tree/master/deploy){:target="_blank"}, we provide the Gateway API deployment yaml files for installation. + +The deployment yaml files are located at: https://github.com/f5devcentral/bigip-kubernetes-gateway/tree/master/deploy. + +The files are numbered and can complete the deployment process in order, where: + +|file name | functionality | notes | +| --- | --- | -- | +| [1.clusterrole-and-binding.yaml](https://github.com/f5devcentral/bigip-kubernetes-gateway/blob/master/deploy/1.clusterrole-and-binding.yaml){:target="_blank"} | Create a user and role with corresponding operation permissions in the k8S cluster | No further input is required | +| [2.install-kubernetes-gatewayapi-CRDs.yaml](https://github.com/f5devcentral/bigip-kubernetes-gateway/blob/master/deploy/2.install-kubernetes-gatewayapi-CRDs.yaml){:target="_blank"} | Install the gateway API CRD and admission deployments | No further input is required | +| [3.deploy-bigip-kubernetes-gateway-controller.yaml](https://github.com/f5devcentral/bigip-kubernetes-gateway/blob/master/deploy/3.deploy-bigip-kubernetes-gateway-controller.yaml){:target="_blank"} | Deploy bigip-kubernetes-gateway controller | Required inputs by user to change BIGIP `password: `, BIGIP Configurations in `bigips: ` and image version in `image: ` | + +Execute the `kubectl` command separately in order: + +```shell +$ kubectl apply -f 1.clusterrole-and-binding.yaml +$ kubectl apply -f 2.install-kubernetes-gatewayapi-CRDs.yaml +$ kubectl apply -f 3.deploy-bigip-kubernetes-gateway-controller.yaml +``` + + +After doing them, the bigip-kubernetes-gateway controller runs as a pod in `kube-system` namespace of the kubernetes cluster watching CRUD events for gateway-related resources. + +* View deployment results via `kubectl get deployment -n kube-system`. +* View the run log via `kubectl logs -f deployment/bigip-kubernetes-gateway -c bigip-kubernetes-gateway-pod -n kube-system` + +For configuration defails in mentioned yaml files, see [Controller Parameters](./parameters.md). \ No newline at end of file diff --git a/docs/quick-start/parameters.md b/docs/quick-start/parameters.md new file mode 100644 index 0000000..cbb52e8 --- /dev/null +++ b/docs/quick-start/parameters.md @@ -0,0 +1,165 @@ +# Parameters + +The examples of the parameters are available in the deployment yaml file placed on the code repository: + +[deploy/3.deploy-bigip-kubernetes-gateway-controller.yaml](https://github.com/f5devcentral/bigip-kubernetes-gateway/blob/master/deploy/3.deploy-bigip-kubernetes-gateway-controller.yaml){:target="_blank"}. + +There are 2 parts of BIG-IP configurations: + +* The password of BIG-IP passed in via a Kubernetes Secret(Part 1). +* Some additional BIG-IP configuration information passed in via a separate Kubernetes Configmap(Part 2). + +In the controller deployment yaml file(Part 3), the two parts of configurations are passed in the form of volume, and the controller reads the specific configuration content of the indicated paths. + +## Part 1: bigip-login + +```yaml +--- + +apiVersion: v1 +kind: Secret +metadata: + name: bigip-login + namespace: kube-system +data: + password: UEBzc3cwcmQxMjM= # base64 password for admin +type: Opaque + +``` + +BIG-IP's `password` for admin is stored in a separate `Secret` type resource for security concern. + +## Part 2: bigip-kubernetes-gateway-configmap + +```yaml +--- + +apiVersion: v1 +kind: ConfigMap +metadata: + name: bigip-kubernetes-gateway-configmap + namespace: kube-system +data: + bigip-kubernetes-gateway-config: | + - management: + username: admin + ipAddress: 10.250.15.180 + port: 443 + flannel: + tunnels: + - name: fl-tunnel + profileName: fl-vxlan + port: 8472 + localAddress: 10.250.18.119 + selfIPs: + - name: flannel-self + ipMask: 10.42.20.1/16 + tunnelName: fl-tunnel + calico: + localAS: &as 64512 + remoteAS: *as +``` + +Within the above configmap, it stores BIG-IP configuration for network setup and resource managements. + +The controller would configure the BIG-IPs as specified to make sure the data plane connection between BIG-IP and the kubernetes cluster is OK. + +The meaning of fields are: + +```yaml + + # BIG-IP management info + - management: + # username, must be amdin currently + username: admin + # management IP address for iControl Rest + ipAddress: 10.250.15.180 + # optional, management port, default to 443 + port: 443 + + # optional, overlay network configuration for flannel CNI mode + flannel: + # tunnels configuration + tunnels: + # tunnel name + - name: fl-tunnel + # tunnel profile name for binding to the very tunnel + profileName: fl-vxlan + # tunnel profile port for binding to the very tunnel + port: 8472 + # the local address for the tunnel(VTEP) + localAddress: 10.250.18.119 + # selfips configuration + selfIPs: + # the name of the self IP address definition + - name: flannel-self + # the IP address associated to the vxlan tunnel + ipMask: 10.42.20.1/16 + # tunnel name, should match one of the tunnels + tunnelName: fl-tunnel + + # optional, underlay network configuration for calico CNI mode + calico: + # AS num on BIG-IP side + localAS: &as 64512 + # AS num on K8S side, generally, it's same as localAS + remoteAS: *as +``` + +Note that, + +* If we don't want to configure BIG-IP in `flannel` mode, just remove/comment the `flannel` parts. It's same to `calico` case. + +* Futher, if we don't want to configure BIG-IP at all, remove/comment both of them, the controller will keep the CNI configurations on BIG-IP as user configure them manually in advance. + +## Part 3: bigip-kubernetes-gateway deployment and service + +```yaml + +--- + +apiVersion: apps/v1 +kind: Deployment +metadata: + name: bigip-kubernetes-gateway + namespace: kube-system +spec: + replicas: 1 + + #... + + spec: + serviceAccountName: k8s-bigip-ctlr + nodeSelector: + node-role.kubernetes.io/control-plane: "true" + # node-role.kubernetes.io/master: "true" + containers: + # use `kubectl logs -f deployment/bigip-kubernetes-gateway -c bigip-kubernetes-gateway-pod -n kube-system` for tracing. + - name: bigip-kubernetes-gateway-pod + image: f5devcentral/bigip-kubernetes-gateway:v0.0.4-20221219 + imagePullPolicy: IfNotPresent + command: ["/bigip-kubernetes-gateway-controller-linux"] + args: [ + "--controller-name=f5.io/gateway-controller-name", + "--bigip-config-directory=/bigip-config", + "--bigip-credential-directory=/bigip-credential", + ] + volumeMounts: + - name: bigip-credential + mountPath: "/bigip-credential" + readOnly: true + - name: bigip-config + mountPath: /bigip-config + readOnly: true + volumes: + - name: bigip-credential + secret: + secretName: bigip-login + - name: bigip-config + configMap: + name: bigip-kubernetes-gateway-configmap + +``` +For the yaml file above, let's pay attention to `image`, `args`, `volumeMounts` and `volumes` parts. + +For details about the usage of the file, See [installation](../quick-start/installation.md). diff --git a/docs/quick-start/uninstall.md b/docs/quick-start/uninstall.md new file mode 100644 index 0000000..9074b1b --- /dev/null +++ b/docs/quick-start/uninstall.md @@ -0,0 +1,11 @@ +# Uninstallation + +The uninstall process is executed in reverse order to the installation process. + +You can refer to the deployment file described in the [installation](./installation.md) section, and execute the following commands to complete the uninstallation: + +```shell +$ kubectl delete -f 3.deploy-bigip-kubernetes-gateway-controller.yaml +$ kubectl delete -f 2.install-kubernetes-gatewayapi-CRDs.yaml +$ kubectl delete -f 1.clusterrole-and-binding.yaml +``` diff --git a/mkdocs.yml b/mkdocs.yml index 09315f8..6b4d0d7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -93,10 +93,11 @@ nav: - RBAC: concepts/rbac.md - Rolespersonas: concepts/rolespersonas.md - Design: - - Overview: Design/index.md + - BIG-IP Controller Overview: Design/bip.md + - BIG-IP Next Controller Overview: Design/bipnext.md # - BIG-IP Providers: Design/gatewayclassrefer.md # - Resource Layout: Design/resources-layout.md - - Guides: + - Guides(For BIG-IP): - Getting started: guides/getstarted.md - Simple Gateway: guides/simple-gateway.md - HTTP Routing: guides/http-routing.md @@ -108,6 +109,10 @@ nav: - gRPC Routing: guides/grpc-routing.md - Common FAQ: Operation-and-troubleshooting/ki.md - Troubleshooting: Operation-and-troubleshooting/trubeshooting.md + + - Guides(For BIG-IP Next): + - Getting started: guides-next/getstarted.md + # - Operations: - Contact Us: - Tech Support: Support-and-contact/index.md