docs: Add all command-line options to list. #806

toothbrush · 2021-06-23T07:38:13Z

Hey, i don't know if this is correct or helpful, but i thought i'd try to go through the code and add all the command-line flags i can find.

I wasn't sure about the description on some of them, feel free to amend or tell me to do it better 😊

toothbrush · 2021-06-23T22:21:51Z

This should address #805, at least somewhat.

docs/content/en/docs/configuration/command-line.md

toothbrush · 2021-06-23T22:28:32Z

@jcmoraisjr, i added a bunch of questions – if you want you can informally reply and i'd be happy to elaborate and fix up the descriptions in the documentation. If this is useful of course. 😄

jcmoraisjr · 2021-06-24T00:15:09Z

Hi Paul, thanks for the time invested on this! The launch functionality is one of the last features we inherited from the old times of k8s/ingress as a dependency (all the current pkg/common/* source files) and wasn't ported to the new controller yet. Launch is responsible for parse and show the command-line options, and some of them we simply don't use. Please give me a few more days, I'll deprecate what we don't use, revise all the inline doc using your questions as a guideline, and will notify here as soon as it's done and PR'ed.

toothbrush · 2021-06-24T00:21:30Z

No problem, give me a ping when i can update this doc. Thanks again for taking the time to address all of this! 🥬 🍌

jcmoraisjr · 2021-07-06T11:27:27Z

I've just added a PR that tries to fix some alignment issues and also some bad descriptions to the help output of command-line options. I hope most of your questions were answered, I'll comment the ones that maybe wasn't and leave here the current output for convenience. Don't hesitate to ping here if you need anything.

$ go run pkg/main.go -h
Usage of :
      --acme-check-period duration                 Time between checks of invalid or expiring certificates (default 24h0m0s)
      --acme-election-id string                    Prefix of the election ID used to choose the acme leader (default "acme-leader")
      --acme-fail-initial-duration duration        The initial time to wait to retry sign a new certificate after a failure. The
                                                   time between retries will grow exponentially until 'acme-fail-max-duration' (default 5m0s)
      --acme-fail-max-duration duration            The maximum time to wait after failing to sign a new certificate (default 8h0m0s)
      --acme-secret-key-name string                Name and an optional namespace of the secret which will store the acme account
                                                   private key. If a namespace is not provided, the secret will be created in the
                                                   same namespace of the controller pod (default "acme-private-key")
      --acme-server                                Enables acme server. This server is used to receive and answer challenges from
                                                   Lets Encrypt or other acme implementations.
      --acme-token-configmap-name string           Name and an optional namespace of the configmap which will store acme tokens
                                                   used to answer the acme challenges. If a namespace is not provided, the secret
                                                   will be created in the same namespace of the controller pod (default "acme-validation-tokens")
      --acme-track-tls-annotation                  Enable tracking of ingress objects annotated with 'kubernetes.io/tls-acme'
      --allow-cross-namespace                      Defines if the ingress controller can reference resources of another
                                                   namespaces. Cannot be used if force-namespace-isolation is true
      --alsologtostderr                            log to standard error as well as files
      --annotations-prefix string                  Defines a comma-separated list of annotation prefix for ingress and service (default "haproxy-ingress.github.io,ingress.kubernetes.io")
      --apiserver-host string                      The address of the Kubernetes Apiserver to connect to in the format of
                                                   protocol://address:port, e.g., http://localhost:8080. If not specified, the
                                                   assumption is that the binary runs inside a Kubernetes cluster and local
                                                   discovery is attempted.
      --backend-shards int                         Defines how much files should be used to configure the haproxy backends
      --buckets-response-time float64Slice         Configures the buckets of the histogram used to compute the response time of
                                                   the haproxy's admin socket. The response time unit is in seconds. (default [0.000500,0.001000,0.002000,0.005000,0.010000])
      --configmap string                           Name of the ConfigMap that contains the custom configuration to use
      --controller-class string                    Defines an alternative controller name this controller should listen to. If
                                                   empty, this controller will listen to ingress resources whose controller's
                                                   IngressClass is 'haproxy-ingress.github.io/controller'. Non empty values add a
                                                   new /path, eg controller-class=staging will make this controller look for
                                                   'haproxy-ingress.github.io/controller/staging'
      --default-backend-service string             Service used to serve a 404 page for the default backend. Takes the form
                                                   namespace/name. The controller uses the first node port of this Service for the
                                                   default backend.
      --default-ssl-certificate string             Name of the secret that contains a SSL certificate to be used as
                                                   default for a HTTPS catch-all server
      --disable-api-warnings                       Declare to disable warnings from the API server.
      --disable-node-list                          DEPRECATED: This flag used to disable node listing due to missing permissions.
                                                   Actually node listing isn't needed and it is always disabled
      --disable-pod-list                           Defines if HAProxy Ingress should disable pod watch and in memory list. Pod
                                                   list is mandatory for drain-support (should not be disabled) and optional for
                                                   blue/green.
      --election-id string                         Election id to be used for status update. (default "ingress-controller-leader")
      --force-namespace-isolation                  Force namespace isolation. This flag is required to avoid the reference of
                                                   secrets, configmaps or the default backend service located in a different
                                                   namespace than the specified in the flag --watch-namespace.
      --health-check-path string                   Defines the URL to be used as health check inside in the default server. (default "/healthz")
      --healthz-port int                           port for healthz endpoint. (default 10254)
      --ignore-ingress-without-class               DEPRECATED, this option is ignored. Use --watch-ingress-without-class
                                                   command-line option instead to define if ingress without class should be
                                                   tracked.
      --ingress-class string                       Name of the IngressClass to route through this controller. (default "haproxy")
      --kubeconfig string                          Path to kubeconfig file with authorization and master location information.
      --log_backtrace_at traceLocation             when logging hits line file:N, emit a stack trace (default :0)
      --log_dir string                             If non-empty, write log files in this directory
      --logtostderr                                log to standard error instead of files
      --master-socket string                       Defines the master CLI unix socket of an external HAProxy running in
                                                   master-worker mode. Defaults to use the embedded HAProxy if not declared.
      --max-old-config-files int                   Maximum old haproxy timestamped config files to allow before being cleaned up.
                                                   A value <= 0 indicates a single non-timestamped config file will be used
      --profiling                                  Enable profiling via web interface host:port/debug/pprof/ (default true)
      --publish-service string                     Service fronting the ingress controllers. Takes the form namespace/name. The
                                                   controller will set the endpoint records on the ingress objects to reflect
                                                   those on the service.
      --rate-limit-update float32                  Maximum of updates per second this controller should perform. Default is 0.5,
                                                   which means wait 2 seconds between Ingress updates in order to add more changes
                                                   in a single reload (default 0.5)
      --reload-strategy string                     Name of the reload strategy. Options are: native or reusesocket (default "reusesocket")
      --report-node-internal-ip-address            Defines if the nodes IP address to be returned in the ingress status should be
                                                   the internal instead of the external IP address
      --sort-backends                              Defines if backend's endpoints should be sorted by name. This option has less
                                                   precedence than --sort-endpoints-by if both are declared.
      --sort-endpoints-by string                   Defines how to sort backend's endpoints. Allowed values are: 'endpoint' - same
                                                   k8s endpoint order (default); 'name' - server/endpoint name;
                                                   'ip' - server/endpoint IP and port; 'random' - shuffle endpoints on every
                                                   haproxy reload
      --stats-collect-processing-period duration   Defines the interval between two consecutive readings of haproxy's Idle_pct.
                                                   haproxy updates Idle_pct every 500ms, which makes that the best configuration
                                                   value. Change to 0 (zero) to disable this metric. (default 500ms)
      --stderrthreshold severity                   logs at or above this threshold go to stderr (default 2)
      --sync-period duration                       Configures the default resync period of Kubernetes' informer factory. (default 10m0s)
      --tcp-services-configmap string              Name of the ConfigMap that contains the definition of the TCP services to
                                                   expose. The key in the map indicates the external port to be used. The value is
                                                   the name of the service with the format namespace/serviceName and the port of
                                                   the service could be a number of the name of the port. The ports 80 and 443 are
                                                   not allowed as external ports. This ports are reserved for the backend
      --update-status                              Indicates if the controller should update the 'status' attribute of all the
                                                   Ingress resources that this controller is tracking. (default true)
      --update-status-on-shutdown                  Indicates if the ingress controller should update the Ingress status
                                                   IP/hostname when the controller is being stopped. (default true)
  -v, --v Level                                    log level for V logs
      --validate-config                            Define if the resulting configuration files should be validated when a dynamic
                                                   update was applied. Default value is false, which means the validation will
                                                   only happen when HAProxy needs to be reloaded. If validation fails, HAProxy
                                                   Ingress will log the error and set the metric 'haproxyingress_update_success'
                                                   as failed (zero)
      --verify-hostname                            Defines if the controller should verify if the provided certificate is valid,
                                                   ie, it's SAN extension has the hostname. (default true)
      --version                                    Shows release information about the Ingress controller
      --vmodule moduleSpec                         comma-separated list of pattern=N settings for file-filtered logging
      --wait-before-shutdown int                   Define time controller waits until it shuts down when SIGTERM signal was
                                                   received
      --wait-before-update duration                Amount of time to wait before start a reconciliation and update haproxy, giving
                                                   the time to receive all/most of the changes of a batch update. (default 200ms)
      --watch-gateway                              Watch and parse resources from the Gateway API
      --watch-ingress-without-class                Defines if this controller should also listen to ingress resources that doesn't
                                                   declare neither the kubernetes.io/ingress.class annotation nor the
                                                   <ingress>.spec.ingressClassName field. Defaults to false
      --watch-namespace string                     Namespace to watch for Ingress. Default is to watch all namespaces
pflag: help requested
exit status 2

toothbrush · 2021-07-07T06:10:50Z

Wow, that looks excellent, thanks – i'll have a look at this later and update the PR. Thank you!

toothbrush · 2021-07-07T06:50:01Z

Alright, i've made some small adjustments based on your answers. Let me know if there's anything else i need to do! 👍

jcmoraisjr

Just a few considerations and I'm done. Btw a pretty good job! Thanks for starting this review.

docs/content/en/docs/configuration/command-line.md

…-namespace.

jcmoraisjr · 2021-07-08T10:40:21Z

lgtm, thanks! merging.

adding or updating the following command-line options: * docs(command-line.md): Clarify empty string default. * docs(command-line.md): Add --apiserver-host. * docs(command-line.md): Consistent whitespace and lines. * docs(command-line.md): Add --configmap. * docs(command-line.md): Add --election-id. * docs(command-line.md): Add --force-namespace-isolation. * docs(command-line.md): Add --health-check-path. * docs(command-line.md): Add --report-node-internal-ip-address. * docs(command-line.md): Add --sync-period. * docs(command-line.md): Add --update-status. * docs(command-line.md): Add --update-status-on-shutdown. * docs(command-line.md): Add --validate-config. * docs(command-line.md): Mention --version. * docs(command-line.md): Mention --force-namespace-isolation in --watch-namespace. * docs(command-line.md): Add --v, logging verbosity.