From 34b43c48e8d0f41b0d6d0b80644027a9c8286dc3 Mon Sep 17 00:00:00 2001 From: Arbaaz Khan Date: Thu, 14 Mar 2024 22:19:58 +0530 Subject: [PATCH] Improve documentation (#3336) --- docs/RELEASE-NOTES.rst | 25 ++++++----- .../customResource/CustomResource.md | 14 ++++-- docs/config_examples/multicluster/README.md | 2 +- ...A-CIS-and-cluster-admin-state-no-pool.yaml | 43 +++++++++++++++++++ ...e-CIS-and-cluster-admin-state-no-pool.yaml | 34 +++++++++++++++ 5 files changed, 103 insertions(+), 15 deletions(-) create mode 100644 docs/config_examples/multicluster/extendedConfigmap/extendedConfigmap-with-admin-state-no-pool/global-spec-config-for-multicluster-with-HA-CIS-and-cluster-admin-state-no-pool.yaml create mode 100644 docs/config_examples/multicluster/extendedConfigmap/extendedConfigmap-with-admin-state-no-pool/global-spec-config-for-multicluster-with-standalone-CIS-and-cluster-admin-state-no-pool.yaml diff --git a/docs/RELEASE-NOTES.rst b/docs/RELEASE-NOTES.rst index 655b766a3..934de04de 100644 --- a/docs/RELEASE-NOTES.rst +++ b/docs/RELEASE-NOTES.rst @@ -8,26 +8,29 @@ Added Functionality ``````````````````` **What's new:** * Multi Cluster - * `Issue 3284 `_: Add support to avoid service pool creation for clusters under maintenance. + * `Issue 3284 `_: Add support to avoid service pool creation for clusters under maintenance. See `Example `_ * Streamline the naming convention for extended service references and multi cluster references annotations. + * See `Example with the updated field names for extendedServiceReferences in VS CRD: `_ + * See `Example the updated field names for multiClusterServices annotation in NextGenRoutes: `_ * CRD - * `Issue 3225 `_: Support for Host Persistence to configure and disable the Persistence in VS Policy Rule action based on host in VirtualServer. - * `Issue 3262 `_: Support for Host Aliases to allow defining multiple hosts in VS CRD. `Example `_. - * `Issue 3263 `_: Support for Host group virtual server name in virtual server to customise the virtual server name when Host Group exists. + * `Issue 3225 `_: Support for Host Persistence to configure and disable the Persistence in VS Policy Rule action based on host in VirtualServer. See `Example `_ + * `Issue 3262 `_: Support for Host Aliases to allow defining multiple hosts in VS CRD. See `Example `_. + * `Issue 3263 `_: Support for Host group virtual server name in virtual server to customise the virtual server name when Host Group exists. See `Example `_ * `Issue 3279 `_: Support for disabling default partition in AS3 legacy nodeport mode. - * `Issue 3295 `_: Support for setting the default pool via policy CRD for virtual server and nextgen routes. `Example `_. - * Support for mix of k8s Secret and bigip reference in TLSProfile. + * `Issue 3295 `_: Support for setting the default pool via policy CRD for virtual server and nextgen routes. See `Example `_. + * `Issue 3239 `_: Support for mix of k8s Secret and bigip reference in TLSProfile. See `Example `_ * Support for setting sslProfile with https monitor in virtualServer and nextgen routes. + * See `Example for Virtual Server CRD `_ + * See `Example for NextGenRoutes `_ * Support self value for SNAT in virtualServer and transportServer. - * Support for pool-member-type auto for CRD, NextGen Routes and multiCluster mode. Please refer `Documentation `. - * Support for CIS deployment parameters "trusted-certs-cfgmap" && "insecure" in CRD and NextGen + * Support for pool-member-type auto for CRD, NextGen Routes and multiCluster mode. Please refer `Documentation `_ + * Support for CIS deployment parameters "trusted-certs-cfgmap" && "insecure" in CRD and NextGen. See `Example `_ * CIS compatible with AS3 3.50 Bug Fixes ```````````` -* `Issue 3230 `_: CRD multicluster configuration triggers Raw response from Big-IP: map[code:422 declarationFullId: message:declaration has duplicate values in rules]. +* `Issue 3230 `_: CRD multicluster configuration triggers Raw response from Big-IP: map[code:422 declarationFullId: message:declaration has duplicate values in rules]. Please refer FAQ in `Documentation `_ * `Issue 3232 `_: Enhance as3 response add the runtime attribute. -* `Issue 3239 `_: Support for mix of k8s Secret and bigip reference in TLSProfile. * `Issue 3266 `_: Improve log when admitting next gen routes. * `Issue 3267 `_: Improve log for certificate host name validation. * `Issue 3268 `_: Handle embedded certificates appropriately when missing SAN and hostnames mismatch. @@ -35,6 +38,8 @@ Bug Fixes * `Issue 3299 `_: Fix for EDNS in AS3 and CCCL modes. * `Issue 3312 `_: CIS 2.15 crashes due to interface conversion panic. * Fix for wildcard domain with multiple hosts in tls profile. +* Improve documentation for HTTP2 profile. Please refer `Documentation `_ + Upgrade notes `````````````` diff --git a/docs/config_examples/customResource/CustomResource.md b/docs/config_examples/customResource/CustomResource.md index 01170f1b1..61d3f975e 100644 --- a/docs/config_examples/customResource/CustomResource.md +++ b/docs/config_examples/customResource/CustomResource.md @@ -48,6 +48,7 @@ This page is created to document the behaviour of CIS in CRD Mode. | PARAMETER | TYPE | REQUIRED | DEFAULT | DESCRIPTION | |----------------------------------|-------------------------------|-----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | host | String | Optional | NA | Virtual Host | +| hostAliases | Array of strings | Optional | NA | Additional host names for a virtual server apart from the primary host | | defaultPool | defaultPool | Optional | NA | Default BIG-IP Pool for virtual server | | pools | List of pool | Required | NA | List of BIG-IP Pool members | | virtualServerAddress | String | Optional | NA | IP4/IP6 Address of BIG-IP Virtual Server. IP address can also be replaced by a reference to a Service_Address. | @@ -59,12 +60,12 @@ This page is created to document the behaviour of CIS in CRD Mode. | tlsProfileName | String | Optional | NA | Describes the TLS profile Name for BIG-IP Virtual Server | | rewriteAppRoot | String | Optional | NA | Rewrites the path in the HTTP Header (and Redirects) from \"/" (root path) to specifed path | | waf | String | Optional | NA | Reference to WAF policy on BIG-IP | -| snat | String | Optional | auto | Reference to SNAT pool on BIG-IP. The supported values are ``none``, ``auto``, ``self`` and the BIG-IP SNATPool path. | +| snat | String | Optional | auto | Reference to SNAT pool on BIG-IP. The supported values are ``none``, ``auto``, ``self`` and the BIG-IP SNATPool path. | | connectionMirroring | String | Optional | NA | Controls connection-mirroring for high-availability.allowed value is "none" or "L4" | | httpTraffic | String | Optional | allow | Configure behavior of HTTP Virtual Server. The allowed values are: allow: allow HTTP (default), none: only HTTPs, redirect: redirect HTTP to HTTPS. | | allowVlans | List of Vlans | Optional | NA | list of Vlan objects to allow traffic from | | hostGroup | String | Optional | NA | Label to group virtualservers with different host names into one in BIG-IP. | -| hostGroupVirtualServerName | String | Optional | NA | Custom name of BIG-IP Virtual Server when hostGroup exists. | +| hostGroupVirtualServerName | String | Optional | NA | Custom name of BIG-IP Virtual Server when hostGroup exists. | | persistenceProfile | String | Optional | cookie | CIS uses the AS3 default persistence profile. VirtualServer CRD resource takes precedence over Policy CRD. Allowed values are existing BIG-IP Persistence profiles. | | htmlProfile | String | Optional | NA | Pathname of existing BIG-IP HTML profile. VirtualServer CRD resource takes precedence over Policy CRD. Allowed values are existing BIG-IP HTML profiles. | | dos | String | Optional | NA | Pathname of existing BIG-IP DoS policy. | @@ -78,10 +79,15 @@ This page is created to document the behaviour of CIS in CRD Mode. | httpMrfRoutingEnabled | boolean | Optional | false | Specifies whether to use the HTTP message routing framework (MRF) functionality. This property is available on BIGIP 14.1 and above. | | additionalVirtualServerAddresses | List of virtualserver address | Optional | NA | List of virtual addresses additional to virtualServerAddress where virtual will be listening on.Uses AS3 virtualAddresses param to expose Virtual server which will listen to each IP address in list | | partition | String | Optional | NA | bigip partition | -| hostPersistence | Object | Optional | NA | Persist session rule action will be added to the VS Policy based on the host. Allowed values are existing BIG-IP Persist session | +| hostPersistence | Object | Optional | NA | Persist session rule action will be added to the VS Policy based on the host. Allowed values are existing BIG-IP Persist session | **Note**: - * **hostGroupVirtualServerName** is valid for Virtual Servers configured with hostGroup. hostGroupVirtualServerName is same in all Virtual Servers definitions in a hostGroup. To update existing hostGrouped Virtual servers with hostGroupVirtualServerName, delete the existing Virtual Servers with that hostGroup and apply after adding hostGroupVirtualServerName to the Virtual Server. + * **hostGroupVirtualServerName** will be considered only when the hostGroup is provided in the Virtual Server. + If you want to set the hostGroupVirtualServerName for the existing Virtual Servers, please delete those + Virtual Servers from the Kubernetes/Openshift cluster and re-apply the Virtual Servers with the hostGroupVirtualServerName. + And please make sure that hostGroupVirtualServerName is same across a hostGroup in Virtual Servers. Virtual Servers + which are in same hostGroup and using hostGroupVirtualServerName, do not get updated unless all the Virtual Servers + have same hostGroupVirtualServerName. **Default Pool Components** diff --git a/docs/config_examples/multicluster/README.md b/docs/config_examples/multicluster/README.md index ed5e98ffb..851ce1dbc 100644 --- a/docs/config_examples/multicluster/README.md +++ b/docs/config_examples/multicluster/README.md @@ -537,7 +537,7 @@ Supported values for adminState are [enable, disable, offline, no-pool]
By default clusters are in enabled state.
**adminState: enable**, all new connections are allowed to the pool members from the cluster.
**adminState: disable**, all new connections except those which match an existing persistence session are not allowed for the pool members from the cluster.
-**adminState: offline**, no new connections are allowed to the pool members from the cluster, even if they match an existing persistence session. +**adminState: offline**, no new connections are allowed to the pool members from the cluster, even if they match an existing persistence session.
**adminState: no-pool**, in ratio mode, a service pool is not created for the affected cluster. For all other modes, pool members from the cluster are not added to the service pool. This configuration is helpful when we don't want to add pool or pool members from a particular cluster due to any reasons(for example cluster is under maintenance).
diff --git a/docs/config_examples/multicluster/extendedConfigmap/extendedConfigmap-with-admin-state-no-pool/global-spec-config-for-multicluster-with-HA-CIS-and-cluster-admin-state-no-pool.yaml b/docs/config_examples/multicluster/extendedConfigmap/extendedConfigmap-with-admin-state-no-pool/global-spec-config-for-multicluster-with-HA-CIS-and-cluster-admin-state-no-pool.yaml new file mode 100644 index 000000000..72474fa9b --- /dev/null +++ b/docs/config_examples/multicluster/extendedConfigmap/extendedConfigmap-with-admin-state-no-pool/global-spec-config-for-multicluster-with-HA-CIS-and-cluster-admin-state-no-pool.yaml @@ -0,0 +1,43 @@ +# Example for the usage of adminState with no-pool value in the extendedConfigmap in case of HA-CIS. +# adminState can be provided for a cluster to mark the state of a particular cluster. +# Supported values for adminState are [enable, disable, offline] +# By default clusters are in enabled state. +# adminState: enable, all new connections are allowed to the pool members from the cluster. +# adminState: disable, all new connections except those which match an existing persistence session are not allowed for the pool members from the cluster. +# adminState: offline, no new connections are allowed to the pool members from the cluster, even if they match an existing persistence session. +# adminState: in ratio mode, a service pool is not created for the affected cluster. For all other modes, pool members from the cluster are not added to the service pool. This configuration is helpful when we don't want to add pool or pool members from a particular cluster due to any reasons(for example cluster is under maintenance). + +apiVersion: v1 +kind: ConfigMap +metadata: + labels: + f5nr: "true" + name: extended-spec-config + namespace: kube-system +data: + extendedSpec: | + mode: active-active + highAvailabilityCIS: + primaryEndPoint: http://10.145.72.114:8001 + probeInterval: 30 + retryInterval: 3 + primaryCluster: + clusterName: cluster1 + secret: default/kubeconfig1 + secondaryCluster: + clusterName: cluster2 + secret: default/kubeconfig2 + adminState: no-pool + externalClustersConfig: + - clusterName: cluster3 + secret: default/kubeconfig3 + adminState: offline + - clusterName: cluster4 + secret: default/kubeconfig4 + adminState: no-pool + extendedRouteSpec: + - allowOverride: false + namespace: foo + policyCR: foo/cr-policy1 + vserverAddr: 10.8.0.4 + vserverName: vs-foo diff --git a/docs/config_examples/multicluster/extendedConfigmap/extendedConfigmap-with-admin-state-no-pool/global-spec-config-for-multicluster-with-standalone-CIS-and-cluster-admin-state-no-pool.yaml b/docs/config_examples/multicluster/extendedConfigmap/extendedConfigmap-with-admin-state-no-pool/global-spec-config-for-multicluster-with-standalone-CIS-and-cluster-admin-state-no-pool.yaml new file mode 100644 index 000000000..519a56f8d --- /dev/null +++ b/docs/config_examples/multicluster/extendedConfigmap/extendedConfigmap-with-admin-state-no-pool/global-spec-config-for-multicluster-with-standalone-CIS-and-cluster-admin-state-no-pool.yaml @@ -0,0 +1,34 @@ +# Example for the usage of adminState with no-pool value in the extendedConfigmap in case of standalone CIS. + +# adminState can be provided for a cluster to mark the state of a particular cluster. +# Supported values for adminState are [enable, disable, offline] +# By default clusters are in enabled state. +# adminState: enable, all new connections are allowed to the pool members from the cluster. +# adminState: disable, all new connections except those which match an existing persistence session are not allowed for the pool members from the cluster. +# adminState: offline, no new connections are allowed to the pool members from the cluster, even if they match an existing persistence session. +# adminState: in ratio mode, a service pool is not created for the affected cluster. For all other modes, pool members from the cluster are not added to the service pool. This configuration is helpful when we don't want to add pool or pool members from a particular cluster due to any reasons(for example cluster is under maintenance). + +apiVersion: v1 +kind: ConfigMap +metadata: + labels: + f5nr: "true" + name: extended-spec-config + namespace: kube-system +data: + extendedSpec: | + mode: ratio # mode parameter can be removed if ratio mode is not required + localClusterAdminState: no-pool # This applies to the local cluster wherever the CIS is running. Other supported values are enable, disable and offline + externalClustersConfig: + - clusterName: cluster3 + secret: default/kubeconfig3 + adminState: offline + - clusterName: cluster4 + secret: default/kubeconfig4 + adminState: no-pool + extendedRouteSpec: + - allowOverride: false + namespace: foo + policyCR: foo/cr-policy1 + vserverAddr: 10.8.0.4 + vserverName: vs-foo