通しで作る: gRPC・Kubernetes・Spanner

syntax = "proto3";
package link.v1;
 
service LinkService {
  rpc CreateLink(CreateLinkRequest) returns (CreateLinkResponse);
  rpc GetLink(GetLinkRequest) returns (GetLinkResponse);
  rpc ListLinks(ListLinksRequest) returns (ListLinksResponse);
}
 
message Link {
  string key = 1;
  string url = 2;
  google.protobuf.Timestamp create_time = 3;
}

make generate    # buf lint && buf generate

# buf.gen.yaml
plugins:
  - remote: buf.build/protocolbuffers/go   # Go: メッセージ
  - remote: buf.build/grpc/go              # Go: サーバーとクライアント
  - remote: buf.build/bufbuild/es          # TypeScript

make emulator
# docker run -d -p 9010:9010 -p 9020:9020 gcr.io/cloud-spanner-emulator/emulator

provider "google" {
  project = "learning-project"
  # 本番ではこの行を消す。認証は Application Default Credentials に任せる
  spanner_custom_endpoint = "http://localhost:9020/v1/"
}
 
resource "google_spanner_instance" "main" {
  name         = "learning-instance"
  config       = "emulator-config"   # 本番では regional-asia-northeast1 など
  display_name = "learning"
  num_nodes    = 1
}
 
resource "google_spanner_database" "links" {
  instance = google_spanner_instance.main.name
  name     = "links"
 
  ddl = [
    <<-SQL
      CREATE TABLE links (
        key        STRING(16)   NOT NULL,
        url        STRING(2048) NOT NULL,
        created_at TIMESTAMP    NOT NULL OPTIONS (allow_commit_timestamp = true),
      ) PRIMARY KEY (key)
    SQL
    ,
    "CREATE INDEX links_by_created_at ON links (created_at DESC)",
  ]
 
  deletion_protection = false   # 学習用。本番では true のまま
}

make schema    # terraform init && terraform apply

type Store interface {
	Create(ctx context.Context, link store.Link) error
	Get(ctx context.Context, key string) (store.Link, error)
	List(ctx context.Context, limit int, after time.Time) ([]store.Link, error)
}

func (s *Spanner) Create(ctx context.Context, link Link) error {
	mutation := spanner.Insert("links",
		[]string{"key", "url", "created_at"},
		// 時刻はサーバー側で決める。クライアントの時計を信用しない
		[]any{link.Key, link.URL, spanner.CommitTimestamp},
	)
	if _, err := s.client.Apply(ctx, []*spanner.Mutation{mutation}); err != nil {
		if spanner.ErrCode(err) == codes.AlreadyExists {
			return ErrAlreadyExists   // 呼び出し側が採番し直せるようにする
		}
		return fmt.Errorf("insert に失敗しました: %w", err)
	}
	return nil
}

for attempt := range createRetries {
	key, err := newKey()
	// ...
	err = s.store.Create(ctx, store.Link{Key: key, URL: req.GetUrl()})
	switch {
	case err == nil:
		return &linkv1.CreateLinkResponse{Link: toProto(saved)}, nil
	case errors.Is(err, store.ErrAlreadyExists):
		slog.WarnContext(ctx, "key collision", "key", key, "attempt", attempt+1)
		continue                      // 諦めずにもう一度
	default:
		return nil, status.Error(codes.Internal, "保存に失敗しました")
	}
}
return nil, status.Error(codes.ResourceExhausted, "キーを採番できませんでした")

return nil, status.Error(codes.InvalidArgument, "url は http または https で始めてください")
return nil, status.Error(codes.NotFound, "そのキーは存在しません")

const transport = createGrpcTransport({ baseUrl: LINK_SERVICE_URL });
const links = createClient(LinkService, transport);
 
// POST /links → CreateLink
const created = await links.createLink({ url: String(body['url'] ?? '') });
send(res, 201, { key: created.link?.key, url: created.link?.url });

function toHttpStatus(error: unknown): number {
  if (!(error instanceof ConnectError)) return 500;
  switch (error.code) {
    case Code.InvalidArgument:   return 400;
    case Code.NotFound:          return 404;
    case Code.AlreadyExists:     return 409;
    case Code.ResourceExhausted: return 429;
    case Code.Unavailable:       return 503;
    default:                     return 500;
  }
}

make test              # メモリに差し替えた単体テスト。数秒
make test-integration  # Spanner エミュレータに対する結合テストも走らせる

type Config struct {
	Store Store
	// 省略時は crypto/rand。テストでは固定の値を返す関数を渡す
	NewKey func() (string, error)
}

// 1回目と2回目で同じキーを返し、3回目に別のキーを返す
svc := newTestServer(t, "dup", "dup", "fresh")

FROM golang:1.25-alpine AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download          # 依存だけ先に。ソースを変えてもここは再利用される
COPY gen ./gen
COPY services/link ./services/link
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" \
    -o /out/server ./services/link/cmd/server
 
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/server /server
USER nonroot:nonroot         # 非 root で動かす
ENTRYPOINT ["/server"]

make images    # 2つビルドして kind に読み込ませる

make cluster   # kind create cluster
make deploy    # エミュレータ → Terraform → link → bff

env:
  - { name: LINK_SERVICE_URL, value: "http://link:8080" }   # localhost ではない

readinessProbe:
  grpc: { port: 8080 }     # 受けられる状態か
livenessProbe:
  grpc: { port: 8080 }     # 生きているか

resources:
  requests: { cpu: 50m, memory: 64Mi }
  limits:   { memory: 256Mi }
securityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  capabilities: { drop: ["ALL"] }

make smoke

作成:
  key=9jjbqVZ
一覧:
{"links":[{"key":"9jjbqVZ","url":"https://example.com/hello"}],"next_page_token":""}
転送:
  302 -> https://example.com/hello
不正な URL:
  400

curl -X POST localhost:19080/links \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com/very/long/url"}'
 
curl -i localhost:19080/9jjbqVZ          # 302 で転送
curl 'localhost:19080/links?page_size=5'

kubectl port-forward svc/link 19001:8080
 
grpcurl -plaintext localhost:19001 list                    # サービス一覧
grpcurl -plaintext localhost:19001 describe link.v1.LinkService   # メソッドの定義
grpcurl -plaintext -d '{}' localhost:19001 grpc.health.v1.Health/Check
grpcurl -plaintext -d '{"url":"https://example.com"}' \
  localhost:19001 link.v1.LinkService/CreateLink

make emulator && make schema
make run-link     # 別のターミナル
make run-bff      # さらに別のターミナル

make down    # kind のクラスタとエミュレータを消す