MOSN hot upgrade

This topic describes how to upgrade the sidecar (MOSN) without affecting the business and how to migrate existing persistent connections.

Sidecar O&M is always challenging for a service mesh, while sidecar upgrades are common at the data plane. This topic describes how to upgrade the sidecar (MOSN) without affecting the business and how to migrate existing persistent connections.

Background

This topic describes why and how MOSN supports hot upgrade. For details about the basic concepts of hot upgrade, see the NGINX vs Envoy vs MOSN hot upgrade.

First, why don’t NGINX and Envoy require a connection-lossless migration solution like MOSN does? This depends on their business scenarios. NGINX and Envoy mainly support the HTTP1 and HTTP2 protocols. The connection: Close request/response header in HTTP1 and GOAWAY frame in HTTP2 allow a client to actively close a connection and establish a new one to a new process. However, common multiplexing protocols such as Dubbo and SOFARPC do not provide control frames, and a request will fail if the connection to the old process is closed.

A common upgrade approach is to: cut off the application’s traffic, for example, by unpublishing the service; upgrade MOSN when no new request is received; and then publish the service again. This process takes a rather long time, and the service is unavailable during this period of time. In addition, the application usage also needs to be considered. Achieving a balance between service availability and the upgrade in a large-scale scenario is difficult. To adapt to business scenarios of MOSN, a persistent-connection migration solution is developed to migrate persistent connections to new processes. The entire procedure is transparent to the client, and no connection needs to be re-established, implementing a request-lossless hot upgrade.

Request-lossless hot upgrade procedure of MOSN

Normal procedure

Normal procedure

  1. A client sends a request to MOSN.
  2. MOSN forwards the request to a server.
  3. The server returns a response to MOSN.
  4. MOSN returns the response to the client.

The preceding figure briefly shows a normal request procedure. Next, we need to migrate TCP1 connections between the client and MOSN. TCP2 connections between MOSN and the server do not need to be migrated, because the server accessed by MOSN is selected through load balancing. The connection/disconnection with the server is not our concern.

Hot upgrade procedure

Trigger conditions

We can trigger a hot upgrade through either of the following methods:

  1. Register a SIGHUP event listener with MOSN, and send a SIGHUP signal to the MOSN process to call ForkExec to generate a new MOSN process.
  2. Directly start a new MOSN process.

Why do we provide two methods? In the beginning, only the first method was supported, which is used by NGINX and Envoy. In this method, we can replace the old MOSN binary file in a virtual machine or container for an upgrade. However, our scenarios require cross-container upgrades. We need to start a new container (a new MOSN process) to implement a hot upgrade. That is why the second method is provided. Cross-container upgrades also require support from operators, but this will not be discussed in detail here.

Interaction procedure

Interaction procedure

Sequence diagram of an interaction procedure

The old MOSN process will start a goroutine to run the ReconfigureHandler() function to listen to a domain socket (reconfig.sock) in the last stage. This operation enables the new MOSN process to detect whether an old MOSN process exists.

  1. func ReconfigureHandler() {
  2.     l, err := net.Listen("unix", types.ReconfigureDomainSocket)
  4.     for {
  5.         uc, err := ul.AcceptUnix()
  6.         _, err = uc.Write([]byte{0})
  7.         reconfigure(false)
  8.     }
  9. }

Both hot upgrade triggering methods start a new MOSN process at last. The new MOSN process will then successively call the GetInheritListeners() and isReconfigure() functions to verify whether an old MOSN process exists (whether the reconfig.sock listener exists). If yes, MOSN starts the migration procedure; otherwise, MOSN starts a normal startup procedure.

  1. // The core procedure is kept.
  2. func GetInheritListeners() ([]net.Listener, net.Conn, error) {
  3.     if !isReconfigure() {
  4.         return nil, nil, nil
  5.     }
  7.     l, err := net.Listen("unix", types.TransferListenDomainSocket)
  8.     uc, err := ul.AcceptUnix()
  9.     _, oobn, _, _, err := uc.ReadMsgUnix(buf, oob)
  10.     file := os.NewFile(fd, "")
  11.     fileListener, err := net.FileListener(file)
  12.     return listeners, uc, nil
  13. }

If the migration procedure starts, the new MOSN process will listen to a new domain socket (listen.sock). This ensures that the old MOSN process can transfer the listen FD to the new MOSN process. sendMsg and recvMsg are used to transfer the listen FD. After receiving the listen FD, the new MOSN process calls the net.FileListener() function to generate a listener. In this case, the new and old MOSN processes have the same listen socket.

  1. // FileListener returns a copy of the network listener corresponding
  2. // to the open file f.
  3. // It is the caller's responsibility to close ln when finished.
  4. // Closing ln does not affect f, and closing f does not affect ln.
  5. func FileListener(f *os.File) (ln Listener, err error) {
  6.     ln, err = fileListener(f)
  7.     if err != nil {
  8.         err = &OpError{Op: "file", Net: "file+net", Source: nil, Addr: fileAddr(f.Name()), Err: err}
  9.     }
  10.     return
  11. }

The migration procedure of MOSN is different from that of NGINX. In NGINX, after the forking is done, the child process automatically inherits the listen FD. However, MOSN starts a new process that is independent from the old one, without a parent-child relationship. Therefore, sendMsg is required for transferring the listen FD.

A total of two domain sockets are used to start the migration and transfer the listen FD.

  • reconfig.sock is the old MOSN listener used by the new MOSN process to verify whether an old MOSN process exists.
  • listen.sock is the new MOSN listener used by the old MOSN process to transfer the listen FD.

These two sockets are actually interchangeable. For example, reconfig.sock can also be used for transferring the listen FD. These two sockets are used for some historical reasons. They can be merged into one later on, to make the code simpler and easier to read.

Let us take a look at the handling procedure of the old MOSN process. After receiving the notification from the new MOSN process, the old MOSN process starts the reconfigure(false) procedure. It first calls sendInheritListeners() to transfer the listen FD to the new MOSN process as described above, and then calls WaitConnectionsDone() to migrate existing persistent connections.

  1. // The core procedure is kept.
  2. func reconfigure(start bool) {
  3.     if start {
  4.         startNewMosn()
  5.         return
  6.     }
  7.     // transfer listen fd
  8.     if notify, err = sendInheritListeners(); err != nil {
  9.         return
  10.     }
  11.     // Wait for all connections to be finished
  12.     WaitConnectionsDone(GracefulTimeout)
  14.     os.Exit(0)
  15. }

After receiving the listen FD, the new MOSN process starts the migration process based on the configurations. Then the new MOSN process starts a goroutine to run TransferServer() to listen to a new domain socket (conn.sock), for receiving persistent connections from the old MOSN process subsequently. The migration function is transferHandler().

  1. func TransferServer(handler types.ConnectionHandler) {
  2.     l, err := net.Listen("unix", types.TransferConnDomainSocket)
  4.     utils.GoWithRecover(func() {
  5.         for {
  6.             c, err := l.Accept()
  7.             go transferHandler(c, handler, &transferMap)
  9.         }
  10.     }, nil)
  11. }

The old MOSN process starts persistent-connection migration through transferRead() and transferWrite(). This is analyzed as follows.

Persistent-connection migration procedure

Persistent-connection migration procedure

First, let us take a look at the migration procedure of a new request.

  1. A client sends a request to MOSN.
  2. MOSN (the old MOSN process) sends the FD and connection status data of TCP1 to New MOSN (the new MOSN process).
  3. New MOSN receives the FD and request data, creates a new connection structure, and sends the connection ID to the MOSN. At this time, New MOSN has a copy of the TCP1 connection.
  4. New MOSN selects a new server by using the load balancer, establishes a TCP3 connection, and forwards the request to the server.
  5. The server returns a response to New MOSN.
  6. New MOSN returns a response to the client based on the copy of TCP1 connection transferred from MOSN.

In the original WaitConnectionsDone() function, s.stopChan has been disabled. In ReadLoop of the connection, a [TransferTimeout, 2 * TransferTimeout] random time interval will be set for the migration procedure. The random interval is intended to discretize the migration time for TCP connections of each client, to ensure smooth migration.

  1. func (c *connection) startReadLoop() {
  2.     var transferTime time.Time
  3.     for {
  4.         select {
  5.         case <-c.stopChan:
  6.             if transferTime.IsZero() {
  7.                 if c.transferCallbacks != nil && c.transferCallbacks() {
  8.                     randTime := time.Duration(rand.Intn(int(TransferTimeout.Nanoseconds())))
  9.                     transferTime = time.Now().Add(TransferTimeout).Add(randTime)
  10.                     log.DefaultLogger.Infof("[network] [read loop] transferTime: Wait %d Second", (TransferTimeout+randTime)/1e9)
  11.                 } else {
  12.                     // set a long time, not transfer connection, wait mosn exit.
  13.                     transferTime = time.Now().Add(10 * TransferTimeout)
  14.                     log.DefaultLogger.Infof("[network] [read loop] not support transfer connection, Connection = %d, Local Address = %+v, Remote Address = %+v",
  15.                         c.id, c.rawConnection.LocalAddr(), c.RemoteAddr())
  16.                 }
  17.             } else {
  18.                 if transferTime.Before(time.Now()) {
  19.                     c.transfer()
  20.                     return
  21.                 }
  22.             }

After one random interval elapses, the c.transfer() function is called. c.notifyTransfer() is used for suspending write operations. No write operation is allowed during migration of read operations, because data confusion will occur if write operations are performed simultaneously in the old and new MOSN processes.

  1. func (c *connection) transfer() {
  2.     c.notifyTransfer()
  3.     id, _ := transferRead(c)
  4.     c.transferWrite(id)
  5. }

Then the transferRead() function is called to transfer the FD and status data of a connection to New MOSN through conn.sock. Similar to migrating the listen FD, New MOSN returns an ID after successful processing. This ID identifies the new connection established by New MOSN and will be used later.

  1. // old mosn transfer readloop
  2. func transferRead(c *connection) (uint64, error) {
  3.     unixConn, err := net.Dial("unix", types.TransferConnDomainSocket)
  5.     file, tlsConn, err := transferGetFile(c)
  7.     uc := unixConn.(*net.UnixConn)
  9.     // send type and TCP FD
  10.     err = transferSendType(uc, file)
  12.     // send header + buffer + TLS
  13.     err = transferReadSendData(uc, tlsConn, c.readBuffer, log.DefaultLogger)
  15.     // recv ID
  16.     id := transferRecvID(uc)
  17.     return id, nil
  18. }

We constructed a simple read transfer protocol, which mainly involves the length of the TCP raw data, the length of the TLS data, the TCP raw data, and the TLS data.

  1. /**
  2.  *  transfer read protocol
  3.  *  header (8 bytes) + (readBuffer data) + TLS
  4.  *
  5.  * 0                       4                       8
  6.  * +-----+-----+-----+-----+-----+-----+-----+-----+
  7.  * |      data length      |     TLS length        |
  8.  * +-----+-----+-----+-----+-----+-----+-----+-----+
  9.  * |                     data                      |
  10.  * +-----+-----+-----+-----+-----+-----+-----+-----+
  11.  * |                     TLS                       |
  12.  * +-----+-----+-----+-----+-----+-----+-----+-----+
  13.  *

Now, let us take a look at the handling procedure of the new MOSN process. After receiving migration requests, the new MOSN process starts a goroutine for each migration request to run the transferHandler() function. The function distinguishes read and write transfer requests based on the protocol read. Read transfer is described first. The new MOSN process calls transferNewConn to generate a new connection structure based on the FD and packets transferred from the old MOSN process. Then the new MOSN process transfers the new connection ID to the old MOSN process.

The new MOSN process starts to read data from the new TCP connection, and proceeds with a normal business request procedure.

  1. func transferHandler(c net.Conn, handler types.ConnectionHandler, transferMap *sync.Map) {
  2.     // recv type
  3.     conn, err := transferRecvType(uc)
  4.     if err != nil {
  5.         log.DefaultLogger.Errorf("[network] [transfer] [handler] transferRecvType error :%v", err)
  6.         return
  7.     }
  9.     if conn != nil {
  10.         // transfer read
  11.         // recv header + buffer
  12.         dataBuf, tlsBuf, err := transferReadRecvData(uc)
  13.         if err != nil {
  14.             log.DefaultLogger.Errorf("[network] [transfer] [handler] transferRecvData error :%v", err)
  15.             return
  16.         }
  17.         connection := transferNewConn(conn, dataBuf, tlsBuf, handler, transferMap)
  18.         if connection != nil {
  19.             transferSendID(uc, connection.id)
  20.         } else {
  21.             transferSendID(uc, transferErr)
  22.         }
  23.     } else {
  24.         // transfer write
  25.         // recv header + buffer
  26.         id, buf, err := transferWriteRecvData(uc)
  27.         if err != nil {
  28.             log.DefaultLogger.Errorf("[network] [transfer] [handler] transferRecvData error :%v", err)
  29.         }
  30.         connection := transferFindConnection(transferMap, uint64(id))
  31.         if connection == nil {
  32.             log.DefaultLogger.Errorf("[network] [transfer] [handler] transferFindConnection failed, id = %d", id)
  33.             return
  34.         }
  35.         err = transferWriteBuffer(connection, buf)
  36.         if err != nil {
  37.             log.DefaultLogger.Errorf("[network] [transfer] [handler] transferWriteBuffer error :%v", err)
  38.             return
  39.         }
  40.     }
  41. }

Then the new MOSN process replaces the old MOSN process, to read data from the TCP1 connection and process the data. For the new request, the entire migration procedure is completed.

Residual-response migration procedure

Residual-response migration procedure

Why is a residual-response migration procedure required? Because of the multiplexing protocol, during the previous migration of read connections, residual responses for TCP2 connections are waiting to be returned to the client. The data may go out of order if both the old and new MOSN processes simultaneously write data to TCP1 connections. Therefore, we want the new MOSN process to uniformly handle the residual responses for TCP2 connections.

  1. The server returns a residual response to MOSN.
  2. MOSN transfers the connection ID and response data previously obtained from New MOSN back to New MOSN through domain socket (conn.sock).
  3. New MOSN queries the TCP1 connection based on the ID and returns the response to the client.

After the transferRead() (the read transfer) ends, the transferWrite() (the write transfer) starts. In this stage, packets to be written and the connection ID previously obtained from New MOSN are sent to New MOSN.

  1. // old mosn transfer writeloop
  2. func transferWrite(c *connection, id uint64) error {
  4.     unixConn, err := net.Dial("unix", types.TransferConnDomainSocket)
  6.     uc := unixConn.(*net.UnixConn)
  7.     err = transferSendType(uc, nil)
  9.     // build net.Buffers to IoBuffer
  10.     buf := transferBuildIoBuffer(c)
  11.     // send header + buffer
  12.     err = transferWriteSendData(uc, int(id), buf)
  13.     if err != nil {
  14.         log.DefaultLogger.Errorf("[network] [transfer] [write] transferWrite failed: %v", err)
  15.         return err
  16.     }
  17.     return nil
  18. }

We constructed a simple write transfer protocol, which mainly involves the length of the TCP raw data, the connection ID, and the TCP raw data.

  1. /*
  2.  *  transfer write protocol
  3.  *  header (8 bytes) + (writeBuffer data)
  4.  *
  5.  * 0                       4                       8
  6.  * +-----+-----+-----+-----+-----+-----+-----+-----+
  7.  * |      data length      |    connection  ID     |
  8.  * +-----+-----+-----+-----+-----+-----+-----+-----+
  9.  * |                     data                      |
  10.  * +-----+-----+-----+-----+-----+-----+-----+-----+
  11.  *
  12. **/

The new MOSN process calls the transferHandler() function to identify the write transfer protocol. Then the new MOSN process calls the transferFindConnection() function to locate the TCP1 connection based on the connection ID, and directly write the data.

Note that new requests are now forwarded to the server through TCP3 connections, and only responses to previous requests will be returned through TCP2 connections. If no response is returned within 2 * TransferTimeout during the entire migration, the requests will time out and fail.

Connection status data

During the connection migration, both the TCP FD and the connection status are migrated so that the new MOSN process knows how to initialize the new connection.

The following status data is involved:

Read buffer

The data that has been read from TCP but has not been processed at the application layer during migration.

Write data

The response data received by MOSN after migration.

TLS status data migration

In case of a TLS encrypted request, the following TLS status data must to be migrated:

  1. Encryption key
  2. Sequence
  3. Read buffer data (encrypted/unencrypted)
  4. Cipher type
  5. TLS version
  1. type TransferTLSInfo struct {
  2.     Vers         uint16
  3.     CipherSuite  uint16
  4.     MasterSecret []byte
  5.     ClientRandom []byte
  6.     ServerRandom []byte
  7.     InSeq        [8]byte
  8.     OutSeq       [8]byte
  9.     RawInput     []byte
  10.     Input        []byte
  11. }

Summary

FD migration is a common operation for persistent connection migration, and can be performed through either sendMsg or connection repair.

The most challenging part in the entire procedure is the migration of the application layer data. The general idea is to migrate all data structures of the application layer to the new process, for example, structures such as protocol headers that have been read. However, this increases the migration complexity, because each protocol needs to be handled separately.

To address this problem, MOSN moves migration to the I/O layer, regardless of the protocols used at the application layer. The original TCP packets are migrated, and then the new MOSN process encodes/decodes the packets to assemble the header and other structures. This is a standard procedure that enables migration without parsing protocols. This migration framework can automatically support any stateless protocols.

You may doubt about the residual-response migration procedure. Why don’t we start migration after all responses are returned? This procedure seems to be unnecessary. The reason is that when we use a multiplexing protocol, requests are being sent all the time. You cannot always find a time point when all responses are returned.

Feedback

For more information about discussions on this issue, go to Github Issue at MOSN smooth upgrade problem #866.

Last modified October 28, 2022: docs: Changes to the v1.2.0 configuration (#217) (d237414)