From 2f7ffdc0966d7cd0bb6f677b5b27901948c31ef4 Mon Sep 17 00:00:00 2001 From: Olivia Song Date: Wed, 12 Jul 2023 13:54:16 -0700 Subject: [PATCH] doc enhancement for waf addons and reconciliation (#3281) * doc enhancement for waf addons and reconciliation * change the default value of sync-period to 10hr --- docs/deploy/configurations.md | 15 ++++++++++++--- docs/guide/ingress/annotations.md | 6 ++++++ docs/how-it-works.md | 4 ++++ helm/aws-load-balancer-controller/values.yaml | 2 +- pkg/config/runtime_config.go | 2 +- 5 files changed, 24 insertions(+), 5 deletions(-) diff --git a/docs/deploy/configurations.md b/docs/deploy/configurations.md index aba728474..bd0c72697 100644 --- a/docs/deploy/configurations.md +++ b/docs/deploy/configurations.md @@ -84,8 +84,8 @@ Currently, you can set only 1 namespace to watch in this flag. See [this Kuberne |enable-leader-election | boolean | true | Enable leader election for the load balancer controller manager. Enabling this will ensure there is only one active controller manager | |enable-pod-readiness-gate-inject | boolean | true | If enabled, targetHealth readiness gate will get injected to the pod spec for the matching endpoint pods | |enable-shield | boolean | true | Enable Shield addon for ALB | -|enable-waf | boolean | true | Enable WAF addon for ALB | -|enable-wafv2 | boolean | true | Enable WAF V2 addon for ALB | +|[enable-waf](#waf-addons) | boolean | true | Enable WAF addon for ALB | +|[enable-wafv2](#waf-addons) | boolean | true | Enable WAF V2 addon for ALB | |external-managed-tags | stringList | | AWS Tag keys that will be managed externally. Specified Tags are ignored during reconciliation | |[feature-gates](#feature-gates) | stringMap | | A set of key=value pairs to enable or disable features | |health-probe-bind-addr | string | :61779 | The address the health probes binds to | @@ -98,7 +98,7 @@ Currently, you can set only 1 namespace to watch in this flag. See [this Kuberne |log-level | string | info | Set the controller log level - info, debug | |metrics-bind-addr | string | :8080 | The address the metric endpoint binds to | |service-max-concurrent-reconciles | int | 3 | Maximum number of concurrently running reconcile loops for service | -|sync-period | duration | 1h0m0s | Period at which the controller forces the repopulation of its local object stores| +|[sync-period](#sync-period) | duration | 10h0m0s | Period at which the controller forces the repopulation of its local object stores| |targetgroupbinding-max-concurrent-reconciles | int | 3 | Maximum number of concurrently running reconcile loops for targetGroupBinding | |targetgroupbinding-max-exponential-backoff-delay | duration | 16m40s | Maximum duration of exponential backoff for targetGroupBinding reconcile failures | |watch-namespace | string | | Namespace the controller watches for updates to Kubernetes objects, If empty, all namespaces are watched. | @@ -127,6 +127,15 @@ Once disabled: * you can no longer create Ingresses with the `alb.ingress.kubernetes.io/group.name` annotation. * you can no longer alter the value of an `alb.ingress.kubernetes.io/group.name` annotation on an existing Ingress. +### sync-period +`--sync-period` defines a fixed interval for the controller to reconcile all resources even if there is no change, default to 10 hr. Please be mindful that frequent reconciliations may incur unnecessary AWS API usage. + +As best practice, we do not recommend users to manually modify the resources managed by the controller. And users should not depend on the controller auto-reconciliation to revert the manual modification, or to mitigate any security risks. + +### waf-addons +By default, the controller assumes sole ownership of the WAF addons associated to the provisioned ALBs, via the flag `--enable-waf` and `--enable-wafv2`. +And the users should disable them accordingly if they want a third party like AWS Firewall Manager to associate or remove the WAF-ACL of the ALBs. +Once disabled, the controller shall not take any actions on the waf addons of the provisioned ALBs. ### throttle config diff --git a/docs/guide/ingress/annotations.md b/docs/guide/ingress/annotations.md index d288c4ba8..2ec721084 100644 --- a/docs/guide/ingress/annotations.md +++ b/docs/guide/ingress/annotations.md @@ -828,6 +828,12 @@ In addition, you can use annotations to specify additional tags ``` ## Addons + +!!!note + If waf-acl-arn is specified via the ingress annotations, the controller will make sure the waf-acl is associated to the provisioned ALB with the ingress. + If there is not such annotation, the controller will make sure no waf-acl is associated, so it may remove the existing waf-acl on the ALB provisioned. + If users do not want the controller to manage the waf-acl on the ALBs, they can disable the feature by setting controller command line flags `--enable-waf=false` or `--enable-wafv2=false` + - `alb.ingress.kubernetes.io/waf-acl-id` specifies the identifier for the Amazon WAF web ACL. !!!warning "" diff --git a/docs/how-it-works.md b/docs/how-it-works.md index cb766c528..ec2fe9105 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -6,6 +6,10 @@ The following diagram details the AWS components this controller creates. It als ![controller-design](assets/images/controller-design.png) +!!!warning "Note" + + The controller manages the configurations of the resources it creates, and we do not recommend out-of-band modifications to these resources because the controller may revert the manual changes during reconciliation. We recommend to use configuration options provided as best practice, such as ingress and service annotations, controller command line flags and IngressClassParams. + ### Ingress Creation This section describes each step (circle) above. This example demonstrates satisfying 1 ingress resource. diff --git a/helm/aws-load-balancer-controller/values.yaml b/helm/aws-load-balancer-controller/values.yaml index dea199559..8e93397be 100644 --- a/helm/aws-load-balancer-controller/values.yaml +++ b/helm/aws-load-balancer-controller/values.yaml @@ -215,7 +215,7 @@ targetgroupbindingMaxConcurrentReconciles: # Maximum duration of exponential backoff for targetGroupBinding reconcile failures targetgroupbindingMaxExponentialBackoffDelay: -# Period at which the controller forces the repopulation of its local object stores. (default 1h0m0s) +# Period at which the controller forces the repopulation of its local object stores. (default 10h0m0s) syncPeriod: # Namespace the controller watches for updates to Kubernetes objects, If empty, all namespaces are watched. diff --git a/pkg/config/runtime_config.go b/pkg/config/runtime_config.go index 7d080cb3f..8688d591c 100644 --- a/pkg/config/runtime_config.go +++ b/pkg/config/runtime_config.go @@ -33,7 +33,7 @@ const ( defaultWatchNamespace = corev1.NamespaceAll defaultMetricsAddr = ":8080" defaultHealthProbeBindAddress = ":61779" - defaultSyncPeriod = 60 * time.Minute + defaultSyncPeriod = 10 * time.Hour defaultWebhookBindPort = 9443 // High enough QPS to fit all expected use cases. QPS=0 is not set here, because // client code is overriding it.