istio.io/istio@v0.0.0-20240520182934-d79c90f27776/pilot/pkg/config/monitor/README.md (about)

     1  # Monitor
     2  
     3  This package provides the ability to populate a `crd.Controller` dynamically via a function that provides
     4  additional config. The monitor will acquire snapshots of additional changes and populate the `crd.Controller`
     5  as needed.
     6  
     7  ## Creating a Monitor
     8  
     9  To create a monitor, you should provide the `crd.Controller`, a polling interval, and
    10  a function that returns `[]*model.Config`.
    11  
    12  ```golang
    13  monitor := file.NewMonitor(
    14      controller,      // The crd controller holding the store and event handlers
    15      1*time.Second,   // How quickly the monitor requests new snapshots
    16      getSnapshotFunc) // The function used to acquire new config
    17  ```
    18  
    19  ## Running a Monitor
    20  
    21  Once created, you simply run the monitor, providing a stop channel.
    22  
    23  ```golang
    24  stop := make(chan struct{})
    25  ...
    26  monitor.Start(stop)
    27  ```
    28  
    29  The `Start` method will kick off an asynchronous polling loop and will return immediately.
    30  
    31  ## Example
    32  
    33  To configure and run a monitor that watches for file changes to update an in-memory config store:
    34  
    35  ```golang
    36  // Configure the config store
    37  store := memory.Make(configDescriptor)
    38  controller = memory.NewController(store)
    39  // Create an object that will take snapshots of config
    40  fileSnapshot := configmonitor.NewFileSnapshot(args.Config.FileDir, configDescriptor)
    41  // Provide snapshot func to monitor
    42  fileMonitor := configmonitor.NewMonitor(controller, 100*time.Millisecond, fileSnapshot.ReadFile)
    43  
    44  // Run the controller and monitor
    45  stop := make(chan struct{})
    46  go controller.run(stop)
    47  monitor.Start(stop)
    48  ```
    49  
    50  See `monitor_test.go` and `file_snapshot_test.go` for more examples.
    51  
    52  ## Notes
    53  
    54  ### Always use a Controller
    55  
    56  While the API supports any `model.ConfigStore`, it is recommended to always use a `crd.Controller` so that other
    57  system components can be notified of changes via `controller.RegisterEventHandler()`.
    58  
    59  ### Start behavior
    60  
    61  The `Start` method will immediately check the provided `getSnapshotFunc` and update the controller appropriately
    62  before returning. This helps to simplify tests that rely on starting in a particular state.
    63  
    64  After performing an initial update, the `Start` method then forks an asynchronous polling loop for update/termination.