소개

raftexample은 etcd raft 합의 알고리즘 라이브러리의 사용을 보여주는 etcd에서 제공하는 예입니다. raftexample은 궁극적으로 REST API를 제공하는 분산 키-값 스토리지 서비스를 구현합니다.

이 글에서는 독자들이 etcd raft 라이브러리 사용 방법과 raft 라이브러리의 구현 로직을 더 잘 이해할 수 있도록 raftexample의 코드를 읽고 분석할 것입니다.

건축학

raftexample의 아키텍처는 매우 간단하며 주요 파일은 다음과 같습니다.

• main.go: raft 모듈, httpapi 모듈 및 kvstore 모듈 간의 상호 작용 구성을 담당합니다.
• raft.go: 제안서 제출, 전송해야 하는 RPC 메시지 수신, 네트워크 전송 수행 등을 포함하여 뗏목 라이브러리와의 상호 작용을 담당합니다.
• httpapi.go: REST API 제공을 담당하며 사용자 요청의 진입점 역할을 합니다.
• kvstore.go: 뗏목 프로토콜의 상태 시스템에 해당하는 커밋된 로그 항목을 지속적으로 저장하는 일을 담당합니다.

쓰기 요청의 처리 흐름

HTTP PUT 요청을 통해 httpapi 모듈의 ServeHTTP 메서드에 쓰기 요청이 도착합니다.

curl -L http://127.0.0.1:12380/key -XPUT -d value

스위치를 통해 HTTP 요청 방법을 일치시킨 후 PUT 방법 처리 흐름으로 들어갑니다.

• HTTP 요청 본문의 내용(즉, 값)을 읽습니다.
• kvstore 모듈의 Propose 메소드를 통해 제안을 구성합니다(키를 키로, 값을 값으로 사용하여 키-값 쌍 추가).
• 반환할 데이터가 없으므로 클라이언트에 204 StatusNoContent;
로 응답합니다.

Raft 알고리즘 라이브러리에서 제공하는 Propose 메소드를 통해 Raft 알고리즘 라이브러리에 제안서를 제출합니다.

제안 내용에는 새 키-값 쌍 추가, 기존 키-값 쌍 업데이트 등이 포함될 수 있습니다.

// httpapi.go
v, err := io.ReadAll(r.Body)
if err != nil {
    log.Printf("Failed to read on PUT (%v)\n", err)
    http.Error(w, "Failed on PUT", http.StatusBadRequest)
    return
}
h.store.Propose(key, string(v))
w.WriteHeader(http.StatusNoContent)

다음으로 kvstore 모듈의 Propose 메소드를 살펴보고 제안이 어떻게 구성되고 처리되는지 살펴보겠습니다.

Propose 메소드에서는 먼저 gob를 사용하여 작성할 키-값 쌍을 인코딩한 다음 인코딩된 콘텐츠를 kvstore 모듈에 의해 생성된 제안을 raft 모듈로 전송하는 채널인 ProposeC에 전달합니다.

// kvstore.go
func (s *kvstore) Propose(k string, v string) {
    var buf strings.Builder
    if err := gob.NewEncoder(&buf).Encode(kv{k, v}); err != nil {
        log.Fatal(err)
    }
    s.proposeC 



kvstore에 의해 생성되어 ProposalC로 전달된 제안은 raft 모듈의serveChannels 메소드에 의해 수신되고 처리됩니다.

raft 모듈은 ProposalC가 종료되지 않았음을 확인한 후 Raft 알고리즘 라이브러리에서 제공하는 Propose 메소드를 사용하여 처리하기 위해 Raft 알고리즘 라이브러리에 제안서를 제출합니다.


// raft.go
select {
    case prop, ok := 



제안서가 제출되면 뗏목 알고리즘 프로세스를 따릅니다. 제안은 결국 리더 노드로 전달됩니다(현재 노드가 리더가 아니고 팔로워가 제안을 전달할 수 있도록 허용한 경우, 비활성화ProposalForwarding 구성에 의해 제어됨). 리더는 제안을 뗏목 로그에 로그 항목으로 추가하고 이를 다른 팔로어 노드와 동기화합니다. 커밋된 것으로 간주된 후 상태 머신에 적용되고 결과가 사용자에게 반환됩니다.

그러나 etcd raft 라이브러리 자체는 노드 간 통신, raft 로그 추가, 상태 머신에 적용 등을 처리하지 않으므로 raft 라이브러리는 이러한 작업에 필요한 데이터만 준비합니다. 실제 작업은 당사가 수행해야 합니다.

따라서 raft 라이브러리에서 이 데이터를 수신하고 해당 유형에 따라 적절하게 처리해야 합니다. Ready 메서드는 처리해야 하는 데이터를 수신할 수 있는 읽기 전용 채널을 반환합니다.


수신된 데이터에는 적용할 스냅샷, 뗏목 로그에 추가할 로그 항목, 네트워크를 통해 전송될 메시지 등 여러 필드가 포함되어 있다는 점에 유의해야 합니다.


쓰기 요청 예시(리더 노드)를 계속 진행하면 해당 데이터를 수신한 후 스냅샷, HardState 및 항목을 지속적으로 저장하여 서버 충돌로 인해 발생한 문제를 처리해야 합니다(예: 팔로어가 여러 후보자에게 투표). HardState와 항목은 함께 문서에 언급된 대로 모든 서버의 영구 상태를 구성합니다. 지속적으로 저장한 후 스냅샷을 적용하고 뗏목 로그에 추가할 수 있습니다.

우리는 현재 리더 노드이므로 raft 라이브러리는 MsgApp 유형 메시지를 우리에게 반환합니다(논문의 AppendEntries RPC에 해당). 우리는 이 메시지를 팔로어 노드로 보내야 합니다. 여기서는 etcd에서 제공하는 rafthttp를 노드 통신에 사용하고 Send 메소드를 사용하여 Follower 노드에 메시지를 보냅니다.


// raft.go
case rd := 



다음으로, 게시엔트리(publishEntries) 메소드를 사용하여 커밋된 래프트 로그 항목을 상태 머신에 적용합니다. 앞서 언급했듯이 raftexample에서는 kvstore 모듈이 상태 머신 역할을 합니다. PublishEntries 메소드에서는 상태 시스템에 적용해야 하는 로그 항목을 commitC에 전달합니다. 이전 ProposalC와 유사하게 commitC는 raft 모듈이 적용을 위해 kvstore 모듈에 커밋된 것으로 간주한 로그 ​​항목을 상태 머신에 전송하는 역할을 담당합니다.


// raft.go
rc.commitC 



kvstore 모듈의 readCommits 메소드에서는 commitC에서 읽은 메시지가 gob 디코딩되어 원래 키-값 쌍을 검색한 다음 kvstore 모듈 내의 맵 구조에 저장됩니다.


// kvstore.go
for commit := range commitC {
    ...
    for _, data := range commit.data {
        var dataKv kv
        dec := gob.NewDecoder(bytes.NewBufferString(data))
        if err := dec.Decode(&dataKv); err != nil {
            log.Fatalf("raftexample: could not decode message (%v)", err)
        }
        s.mu.Lock()
        s.kvStore[dataKv.Key] = dataKv.Val
        s.mu.Unlock()
    }
    close(commit.applyDoneC)
}




뗏목 모듈로 돌아가서 Advance 메서드를 사용하여 Ready 채널에서 읽은 데이터 처리를 마쳤으며 다음 데이터 배치를 처리할 준비가 되었음을 뗏목 라이브러리에 알립니다.

이전에 리더 노드에서는 Send 메서드를 사용하여 팔로어 노드에 MsgApp 유형 메시지를 보냈습니다. 팔로어 노드의 rafthttp는 해당 포트에서 요청을 수신하고 응답을 반환합니다. 팔로어 노드에서 받은 요청이든 리더 노드에서 받은 응답이든 Step 메서드를 통해 처리하기 위해 Raft 라이브러리에 제출됩니다.


raftNode는 rafthttp에서 Raft 인터페이스를 구현하고 Raft 인터페이스의 Process 메소드를 호출하여 수신된 요청 콘텐츠(예: MsgApp 메시지)를 처리합니다.



// raft.go
func (rc *raftNode) Process(ctx context.Context, m raftpb.Message) error {
    return rc.node.Step(ctx, m)
}




위는 raftexample에서 쓰기 요청의 전체 처리 흐름을 설명합니다.


  
  
  요약


 이것으로 이 글의 내용을 마치겠습니다. Raftexample의 구조를 간략하게 설명하고 쓰기 요청의 처리 흐름을 자세히 설명함으로써 etcd raft 라이브러리를 사용하여 자신만의 분산형 KV 스토리지 서비스를 구축하는 방법을 더 잘 이해하는 데 도움이 되기를 바랍니다.

잘못된 점이나 문제가 있으면 댓글이나 직접 메시지로 알려주세요. 감사합니다.


  
  
  참고자료

• https://github.com/etcd-io/etcd/tree/main/contrib/raftexample

• https://github.com/etcd-io/raft

• https://raft.github.io/raft.pdf