"Fossies" - the Fresh Open Source Software Archive

Member "octavia-8.0.0/doc/source/admin/log-offloading.rst" (14 Apr 2021, 11036 Bytes) of package /linux/misc/openstack/octavia-8.0.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) reStructured Text source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 ..
    2       Copyright 2019 Red Hat, Inc. All rights reserved.
    3 
    4       Licensed under the Apache License, Version 2.0 (the "License"); you may
    5       not use this file except in compliance with the License. You may obtain
    6       a copy of the License at
    7 
    8           http://www.apache.org/licenses/LICENSE-2.0
    9 
   10       Unless required by applicable law or agreed to in writing, software
   11       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
   12       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
   13       License for the specific language governing permissions and limitations
   14       under the License.
   15 
   16 ==============================
   17 Octavia Amphora Log Offloading
   18 ==============================
   19 
   20 The default logging configuration will store the logs locally, on the amphora
   21 filesystem with file rotation.
   22 
   23 Octavia Amphorae can offload their log files via the syslog protocol to syslog
   24 receivers via the load balancer management network (lb-mgmt-net). This allows
   25 log aggregation of both administrative logs and also tenant traffic flow logs.
   26 The syslog receivers can either be local to the load balancer management
   27 network or routable via the load balancer management network.
   28 By default any syslog receiver that supports UDP or TCP syslog protocol can
   29 be used, however the operator also has the option to create an override
   30 rsyslog configuration template to enable other features or protocols their
   31 Amphora image may support.
   32 
   33 This guide will discuss the features of :term:`Amphora` log offloading and how
   34 to configure them.
   35 
   36 Administrative Logs
   37 ===================
   38 
   39 The administrative log offloading feature of the :term:`Amphora` covers all of
   40 the system logging inside the :term:`Amphora` except for the tenant flow logs.
   41 Tenant flow logs can be sent to and processed by the same syslog receiver used
   42 by the administrative logs, but they are configured separately.
   43 
   44 All administrative log messages will be sent using the native log format
   45 for the application sending the message.
   46 
   47 Enabling Administrative Log Offloading
   48 --------------------------------------
   49 
   50 One or more syslog receiver endpoints must be configured in the Octavia
   51 configuration file to enable administrative log offloading. The first endpoint
   52 will be the primary endpoint to receive the syslog packets. Should the first
   53 endpoint become unavailable, the additional endpoints listed will be tried
   54 one at a time.
   55 
   56 .. note::
   57 
   58     Secondary syslog endpoints will only be used if the log_protocol is
   59     configured for TCP. With the UDP syslog protocol, rsyslog is unable
   60     to detect if the primary endpoint has failed.
   61 
   62 To configure administrative log offloading, set the following setting in your
   63 Octavia configuration file for all of the controllers and restart them:
   64 
   65 .. code-block:: ini
   66 
   67     [amphora_agent]
   68     admin_log_targets = 192.0.2.1:10514, 2001:db8:1::10:10514
   69 
   70 In this example, the primary syslog receiver will be 192.0.2.1 on port 10514.
   71 The backup syslog receiver will be 2001:db8:1::10 on port 10514.
   72 
   73 .. note::
   74 
   75     Make sure your syslog receiver endpoints are accessible from the load
   76     balancer management network and you have configured the required
   77     security group or firewall rules to allow the traffic. These endpoints
   78     can be routable addresses from the load balancer management network.
   79 
   80 The load balancer related administrative logs will be sent using a
   81 LOG_LOCAL[0-7] facility. The facility number defaults to 1, but is configurable
   82 using the administrative_log_facility setting in the Octavia configuration
   83 file.
   84 
   85 To configure administrative log facility, set the following setting in your
   86 Octavia configuration file for all of the controllers and restart them:
   87 
   88 .. code-block:: ini
   89 
   90     [amphora_agent]
   91     administrative_log_facility = 1
   92 
   93 Forwarding All Administrative Logs
   94 ----------------------------------
   95 
   96 By default, the Amphorae will only forward load balancer related administrative
   97 logs, such as the haproxy admin logs, keepalived, and :term:`Amphora` agent
   98 logs.
   99 You can optionally configure the Amphorae to send all of the administrative
  100 logs from the :term:`Amphora`, such as the kernel, system, and security logs.
  101 Even with this setting the tenant flow logs will not be included. You can
  102 configure tenant flow log forwarding in the `Tenant Flow Logs`_ section.
  103 
  104 The load balancer related administrative logs will be sent using the
  105 LOG_LOCAL[0-7] configured using the administrative_log_facility setting. All
  106 other administrative log messages will use their native syslog facilities.
  107 
  108 To configure the Amphorae to forward all administrative logs, set the following
  109 setting in your Octavia configuration file for all of the controllers and
  110 restart them:
  111 
  112 .. code-block:: ini
  113 
  114     [amphora_agent]
  115     forward_all_logs = True
  116 
  117 Tenant Flow Logs
  118 ================
  119 
  120 Enabling Tenant Flow Log Offloading
  121 -----------------------------------
  122 
  123 One or more syslog receiver endpoints must be configured in the Octavia
  124 configuration file to enable tenant flow log offloading. The first endpoint
  125 will be the primary endpoint to receive the syslog packets. Should the first
  126 endpoint become unavailable, the additional endpoints listed will be tried
  127 one at a time. The endpoints configured for tenant flow log offloading may be
  128 the same endpoints as the administrative log offloading configuration.
  129 
  130 .. warning::
  131 
  132     Tenant flow logging can produce a large number of syslog messages
  133     depending on how many connections the load balancers are receiving.
  134     Tenant flow logging produces one log entry per connection to the
  135     load balancer. We recommend you monitor, size, and configure your syslog
  136     receivers appropriately based on the expected number of connections your
  137     load balancers will be handling.
  138 
  139 .. note::
  140 
  141     Secondary syslog endpoints will only be used if the log_protocol is
  142     configured for TCP. With the UDP syslog protocol, rsyslog is unable
  143     to detect if the primary endpoint has failed.
  144 
  145 To configure tenant flow log offloading, set the following setting in your
  146 Octavia configuration file for all of the controllers and restart them:
  147 
  148 .. code-block:: ini
  149 
  150     [amphora_agent]
  151     tenant_log_targets = 192.0.2.1:10514, 2001:db8:1::10:10514
  152 
  153 In this example, the primary syslog receiver will be 192.0.2.1 on port 10514.
  154 The backup syslog receiver will be 2001:db8:1::10 on port 10514.
  155 
  156 .. note::
  157 
  158     Make sure your syslog receiver endpoints are accessible from the load
  159     balancer management network and you have configured the required
  160     security group or firewall rules to allow the traffic. These endpoints
  161     can be routable addresses from the load balancer management network.
  162 
  163 The load balancer related tenant flow logs will be sent using a
  164 LOG_LOCAL[0-7] facility. The facility number defaults to 0, but is configurable
  165 using the user_log_facility setting in the Octavia configuration file.
  166 
  167 To configure the tenant flow log facility, set the following setting in your
  168 Octavia configuration file for all of the controllers and restart them:
  169 
  170 .. code-block:: ini
  171 
  172     [amphora_agent]
  173     user_log_facility = 0
  174 
  175 Tenant Flow Log Format
  176 ----------------------
  177 
  178 The default tenant flow log format is:
  179 
  180 .. code-block::
  181 
  182     project_id loadbalancer_id listener_id client_ip client_port data_time
  183     request_string http_status bytes_read bytes_uploaded
  184     client_certificate_verify(0 or 1) client_certificate_distinguised_name
  185     pool_id member_id processing_time(ms) termination_state
  186 
  187 Any field that is unknown or not applicable to the connection will have a '-'
  188 character in its place.
  189 
  190 An example log entry when using rsyslog as the syslog receiver is:
  191 
  192 .. note::
  193 
  194     The prefix[1] in this example comes from the rsyslog receiver and is not
  195     part of the syslog message from the amphora.
  196 
  197     [1] "Jun 12 00:44:13 amphora-3e0239c3-5496-4215-b76c-6abbe18de573 haproxy[1644]:"
  198 
  199 .. code-block::
  200 
  201     Jun 12 00:44:13 amphora-3e0239c3-5496-4215-b76c-6abbe18de573 haproxy[1644]: 5408b89aa45b48c69a53dca1aaec58db fd8f23df-960b-4b12-ba62-2b1dff661ee7 261ecfc2-9e8e-4bba-9ec2-3c903459a895 172.24.4.1 41152 12/Jun/2019:00:44:13.030 "GET / HTTP/1.1" 200 76 73 - "" e37e0e04-68a3-435b-876c-cffe4f2138a4 6f2720b3-27dc-4496-9039-1aafe2fee105 4 --
  202 
  203 Custom Tenant Flow Log Format
  204 -----------------------------
  205 
  206 You can optionally specify a custom log format for the tenant flow logs.
  207 This string follows the HAProxy log format variables with the exception of
  208 the "{{ project_id }}" and "{{ lb_id }}" variables that will be replaced
  209 by the Octavia :term:`Amphora` driver. These custom variables are optional.
  210 
  211 See the HAProxy documentation for `Custom log format <http://cbonte.github.io/haproxy-dconv/1.9/configuration.html#8.2.4>`_ variable definitions.
  212 
  213 To configure a custom log format, set the following setting in your
  214 Octavia configuration file for all of the controllers and restart them:
  215 
  216 .. code-block:: ini
  217 
  218     [haproxy_amphora]
  219     user_log_format = '{{ project_id }} {{ lb_id }} %f %ci %cp %t %{+Q}r %ST %B %U %[ssl_c_verify] %{+Q}[ssl_c_s_dn] %b %s %Tt %tsc'
  220 
  221 Disabling Logging
  222 =================
  223 
  224 There may be cases where you need to disable logging inside the
  225 :term:`Amphora`, such as complying with regulatory standards.
  226 Octavia provides multiple options for disabling :term:`Amphora` logging.
  227 
  228 Disable Local Log Storage
  229 -------------------------
  230 
  231 This setting stops log entries from being written to the disk inside the
  232 :term:`Amphora`. Logs can still be sent via :term:`Amphora` log offloading if
  233 log offloading is configured for the Amphorae. Enabling this setting may
  234 provide a performance benefit to the load balancer.
  235 
  236 .. warning::
  237 
  238     This feature disables ALL log storage in the :term:`Amphora`, including
  239     kernel, system, and security logging.
  240 
  241 .. note::
  242 
  243     If you enable this setting and are not using :term:`Amphora` log
  244     offloading, we recommend you also `Disable Tenant Flow Logging`_ to
  245     improve load balancing performance.
  246 
  247 To disable local log storage in the :term:`Amphora`, set the following setting
  248 in your Octavia configuration file for all of the controllers and restart them:
  249 
  250 .. code-block:: ini
  251 
  252     [amphora_agent]
  253     disable_local_log_storage = True
  254 
  255 Disable Tenant Flow Logging
  256 ---------------------------
  257 
  258 This setting allows you to disable tenant flow logging irrespective of the
  259 other logging configuration settings. It will take precedent over the other
  260 settings. When this setting is enabled, no tenant flow (connection) logs will
  261 be written to the disk inside the :term:`Amphora` or be sent via the
  262 :term:`Amphora` log offloading.
  263 
  264 .. note::
  265 
  266     Disabling tenant flow logging can also improve the load balancing
  267     performance of the amphora. Due to the potential performance improvement,
  268     we recommend you enable this setting when using the
  269     `Disable Local Log Storage`_ setting.
  270 
  271 To disable tenant flow logging, set the following setting in your Octavia
  272 configuration file for all of the controllers and restart them:
  273 
  274 .. code-block:: ini
  275 
  276     [haproxy_amphora]
  277     connection_logging = False