From ce96d82de046a56f858ae232441970549172c292 Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Fri, 20 Aug 2021 16:07:18 -0700 Subject: [PATCH] build: Centralize our protobuf compilation steps We have a few different .proto files in this repository that all need to get recompiled into .pb.go files each time we change them, but we were previously handling that with some scripts that just assumed that protoc and the relevant plugins were already installed on the system somewhere, at the right versions. In practice we've been constantly flopping between different versions of these tools due to folks having different versions installed in their development environments. In particular, the state of the .pb.go files in the prior commit wasn't reproducible by any single version of the tools because they've all slightly diverged from one another. In the interests of being more consistent here and avoiding accidental inconsistencies, we'll now centralize the protocol buffer compile steps all into a single tool that knows how to fetch and install the expected versions of the various tools we need and then run those tools with the right options to get a stable result. If we want to upgrade to either a newer protoc or a newer protoc-gen-go in future then we'll do that in a central location and update all of the .pb.go files at the same time, so that we're always consistently tracking the same version of protocol buffers everywhere. While doing this I attempted to keep as close as possible to the toolchain we'd most recently used, but since they were not consistent with each other they've now all changed which version numbers they record at minimum, and the planproto stub in particular now also has a slightly different descriptor serialization but is otherwise offering the same API. --- Makefile | 9 +- go.mod | 1 + go.sum | 2 + internal/plans/internal/planproto/generate.sh | 16 -- .../plans/internal/planproto/planfile.pb.go | 16 +- internal/tfplugin5/generate.sh | 16 -- internal/tfplugin5/tfplugin5.pb.go | 2 +- internal/tfplugin6/generate.sh | 16 -- internal/tfplugin6/tfplugin6.pb.go | 4 +- scripts/protobuf-check.sh | 27 -- tools/protobuf-compile/.workdir/.gitignore | 5 + tools/protobuf-compile/protobuf-compile.go | 233 ++++++++++++++++++ tools/tools.go | 2 + 13 files changed, 261 insertions(+), 88 deletions(-) delete mode 100644 internal/plans/internal/planproto/generate.sh delete mode 100644 internal/tfplugin5/generate.sh delete mode 100644 internal/tfplugin6/generate.sh delete mode 100755 scripts/protobuf-check.sh create mode 100644 tools/protobuf-compile/.workdir/.gitignore create mode 100644 tools/protobuf-compile/protobuf-compile.go diff --git a/Makefile b/Makefile index 20f2862aba..ede1c5cd64 100644 --- a/Makefile +++ b/Makefile @@ -11,12 +11,11 @@ generate: # Terraform do not involve changing protobuf files and protoc is not a # go-gettable dependency and so getting it installed can be inconvenient. # -# If you are working on changes to protobuf interfaces you may either use -# this target or run the individual scripts below directly. +# If you are working on changes to protobuf interfaces, run this Makefile +# target to be sure to regenerate all of the protobuf stubs using the expected +# versions of protoc and the protoc Go plugins. protobuf: - bash scripts/protobuf-check.sh - bash internal/tfplugin5/generate.sh - bash internal/plans/internal/planproto/generate.sh + go run ./tools/protobuf-compile . fmtcheck: @sh -c "'$(CURDIR)/scripts/gofmtcheck.sh'" diff --git a/go.mod b/go.mod index 9dde96fdf7..889cea2d5b 100644 --- a/go.mod +++ b/go.mod @@ -166,6 +166,7 @@ require ( google.golang.org/appengine v1.6.7 // indirect google.golang.org/genproto v0.0.0-20210319143718-93e7006c17a6 // indirect google.golang.org/grpc v1.36.0 + google.golang.org/grpc/cmd/protoc-gen-go-grpc v1.1.0 google.golang.org/protobuf v1.25.0 gopkg.in/inf.v0 v0.9.0 // indirect gopkg.in/ini.v1 v1.42.0 // indirect diff --git a/go.sum b/go.sum index 076211c722..a1c2fd9b4d 100644 --- a/go.sum +++ b/go.sum @@ -1011,6 +1011,8 @@ google.golang.org/grpc v1.31.1/go.mod h1:N36X2cJ7JwdamYAgDz+s+rVMFjt3numwzf/HckM google.golang.org/grpc v1.33.2/go.mod h1:JMHMWHQWaTccqQQlmk3MJZS+GWXOdAesneDmEnv2fbc= google.golang.org/grpc v1.34.0/go.mod h1:WotjhfgOW/POjDeRt8vscBtXq+2VjORFy659qA51WJ8= google.golang.org/grpc v1.35.0/go.mod h1:qjiiYl8FncCW8feJPdyg3v6XW24KsRHe+dy9BAGRRjU= +google.golang.org/grpc/cmd/protoc-gen-go-grpc v1.1.0 h1:M1YKkFIboKNieVO5DLUEVzQfGwJD30Nv2jfUgzb5UcE= +google.golang.org/grpc/cmd/protoc-gen-go-grpc v1.1.0/go.mod h1:6Kw0yEErY5E/yWrBtf03jp27GLLJujG4z/JK95pnjjw= google.golang.org/protobuf v0.0.0-20200109180630-ec00e32a8dfd/go.mod h1:DFci5gLYBciE7Vtevhsrf46CRTquxDuWsQurQQe4oz8= google.golang.org/protobuf v0.0.0-20200221191635-4d8936d0db64/go.mod h1:kwYJMbMJ01Woi6D6+Kah6886xMZcty6N08ah7+eCXa0= google.golang.org/protobuf v0.0.0-20200228230310-ab0ca4ff8a60/go.mod h1:cfTl7dwQJ+fmap5saPgwCLgHXTUD7jkjRqWcaiX5VyM= diff --git a/internal/plans/internal/planproto/generate.sh b/internal/plans/internal/planproto/generate.sh deleted file mode 100644 index 8603edfbb4..0000000000 --- a/internal/plans/internal/planproto/generate.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/bash - -# We do not run protoc under go:generate because we want to ensure that all -# dependencies of go:generate are "go get"-able for general dev environment -# usability. To compile all protobuf files in this repository, run -# "make protobuf" at the top-level. - -set -eu - -SOURCE="${BASH_SOURCE[0]}" -while [ -h "$SOURCE" ] ; do SOURCE="$(readlink "$SOURCE")"; done -DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )" - -cd "$DIR" - -protoc --go_out=paths=source_relative:. planfile.proto diff --git a/internal/plans/internal/planproto/planfile.pb.go b/internal/plans/internal/planproto/planfile.pb.go index faa7e3301f..e5e6dc7aca 100644 --- a/internal/plans/internal/planproto/planfile.pb.go +++ b/internal/plans/internal/planproto/planfile.pb.go @@ -1,12 +1,13 @@ // Code generated by protoc-gen-go. DO NOT EDIT. // versions: -// protoc-gen-go v1.26.0 +// protoc-gen-go v1.25.0 // protoc v3.15.6 // source: planfile.proto package planproto import ( + proto "github.com/golang/protobuf/proto" protoreflect "google.golang.org/protobuf/reflect/protoreflect" protoimpl "google.golang.org/protobuf/runtime/protoimpl" reflect "reflect" @@ -20,6 +21,10 @@ const ( _ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20) ) +// This is a compile-time assertion that a sufficiently up-to-date version +// of the legacy proto package is being used. +const _ = proto.ProtoPackageIsVersion4 + // Mode describes the planning mode that created the plan. type Mode int32 @@ -1192,11 +1197,12 @@ var file_planfile_proto_rawDesc = []byte{ 0x10, 0x01, 0x12, 0x16, 0x0a, 0x12, 0x52, 0x45, 0x50, 0x4c, 0x41, 0x43, 0x45, 0x5f, 0x42, 0x59, 0x5f, 0x52, 0x45, 0x51, 0x55, 0x45, 0x53, 0x54, 0x10, 0x02, 0x12, 0x21, 0x0a, 0x1d, 0x52, 0x45, 0x50, 0x4c, 0x41, 0x43, 0x45, 0x5f, 0x42, 0x45, 0x43, 0x41, 0x55, 0x53, 0x45, 0x5f, 0x43, 0x41, - 0x4e, 0x4e, 0x4f, 0x54, 0x5f, 0x55, 0x50, 0x44, 0x41, 0x54, 0x45, 0x10, 0x03, 0x42, 0x39, 0x5a, - 0x37, 0x67, 0x69, 0x74, 0x68, 0x75, 0x62, 0x2e, 0x63, 0x6f, 0x6d, 0x2f, 0x68, 0x61, 0x73, 0x68, + 0x4e, 0x4e, 0x4f, 0x54, 0x5f, 0x55, 0x50, 0x44, 0x41, 0x54, 0x45, 0x10, 0x03, 0x42, 0x42, 0x5a, + 0x40, 0x67, 0x69, 0x74, 0x68, 0x75, 0x62, 0x2e, 0x63, 0x6f, 0x6d, 0x2f, 0x68, 0x61, 0x73, 0x68, 0x69, 0x63, 0x6f, 0x72, 0x70, 0x2f, 0x74, 0x65, 0x72, 0x72, 0x61, 0x66, 0x6f, 0x72, 0x6d, 0x2f, - 0x70, 0x6c, 0x61, 0x6e, 0x73, 0x2f, 0x69, 0x6e, 0x74, 0x65, 0x72, 0x6e, 0x61, 0x6c, 0x2f, 0x70, - 0x6c, 0x61, 0x6e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x62, 0x06, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x33, + 0x69, 0x6e, 0x74, 0x65, 0x72, 0x6e, 0x61, 0x6c, 0x2f, 0x70, 0x6c, 0x61, 0x6e, 0x73, 0x2f, 0x69, + 0x6e, 0x74, 0x65, 0x72, 0x6e, 0x61, 0x6c, 0x2f, 0x70, 0x6c, 0x61, 0x6e, 0x70, 0x72, 0x6f, 0x74, + 0x6f, 0x62, 0x06, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x33, } var ( diff --git a/internal/tfplugin5/generate.sh b/internal/tfplugin5/generate.sh deleted file mode 100644 index 2fc3453ff0..0000000000 --- a/internal/tfplugin5/generate.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/bash - -# We do not run protoc under go:generate because we want to ensure that all -# dependencies of go:generate are "go get"-able for general dev environment -# usability. To compile all protobuf files in this repository, run -# "make protobuf" at the top-level. - -set -eu - -SOURCE="${BASH_SOURCE[0]}" -while [ -h "$SOURCE" ] ; do SOURCE="$(readlink "$SOURCE")"; done -DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )" - -cd "$DIR" - -protoc --go_out=paths=source_relative,plugins=grpc:. ./tfplugin5.proto diff --git a/internal/tfplugin5/tfplugin5.pb.go b/internal/tfplugin5/tfplugin5.pb.go index 5ace897369..d7db5a4f64 100644 --- a/internal/tfplugin5/tfplugin5.pb.go +++ b/internal/tfplugin5/tfplugin5.pb.go @@ -20,7 +20,7 @@ // Code generated by protoc-gen-go. DO NOT EDIT. // versions: // protoc-gen-go v1.25.0 -// protoc v3.14.0 +// protoc v3.15.6 // source: tfplugin5.proto package tfplugin5 diff --git a/internal/tfplugin6/generate.sh b/internal/tfplugin6/generate.sh deleted file mode 100644 index 0dca95b2bb..0000000000 --- a/internal/tfplugin6/generate.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/bash - -# We do not run protoc under go:generate because we want to ensure that all -# dependencies of go:generate are "go get"-able for general dev environment -# usability. To compile all protobuf files in this repository, run -# "make protobuf" at the top-level. - -set -eu - -SOURCE="${BASH_SOURCE[0]}" -while [ -h "$SOURCE" ] ; do SOURCE="$(readlink "$SOURCE")"; done -DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )" - -cd "$DIR" - -protoc --go_out=paths=source_relative,plugins=grpc:. ./tfplugin6.proto diff --git a/internal/tfplugin6/tfplugin6.pb.go b/internal/tfplugin6/tfplugin6.pb.go index fa89050b28..afd77a0eed 100644 --- a/internal/tfplugin6/tfplugin6.pb.go +++ b/internal/tfplugin6/tfplugin6.pb.go @@ -19,8 +19,8 @@ // Code generated by protoc-gen-go. DO NOT EDIT. // versions: -// protoc-gen-go v1.23.0 -// protoc v3.13.0 +// protoc-gen-go v1.25.0 +// protoc v3.15.6 // source: tfplugin6.proto package tfplugin6 diff --git a/scripts/protobuf-check.sh b/scripts/protobuf-check.sh deleted file mode 100755 index a64315c53a..0000000000 --- a/scripts/protobuf-check.sh +++ /dev/null @@ -1,27 +0,0 @@ -#!/usr/bin/env bash - -# Check whether protobuf & go plugin are installed -PROTOC_HELP_URL="http://google.github.io/proto-lens/installing-protoc.html" -PROTOC_GEN_GO_HELP_URL="https://github.com/golang/protobuf/tree/v1.3.2#installation" - -EXIT_CODE=0 - -which protoc >/dev/null -if [ $? -ne 0 ]; then - echo "Protocol Buffers not found." - echo "Please install Protocol Buffers and ensure 'protoc' is available in your PATH." - echo "See ${PROTOC_HELP_URL} for more." - echo - EXIT_CODE=1 -fi - -which protoc-gen-go >/dev/null -if [ $? -ne 0 ]; then - echo "Protocol Buffers Go plugin not found." - echo "Please install the plugin and ensure 'protoc-gen-go' is available in your PATH." - echo "See ${PROTOC_GEN_GO_HELP_URL} for more." - echo - EXIT_CODE=1 -fi - -exit $EXIT_CODE diff --git a/tools/protobuf-compile/.workdir/.gitignore b/tools/protobuf-compile/.workdir/.gitignore new file mode 100644 index 0000000000..de2eb88ea0 --- /dev/null +++ b/tools/protobuf-compile/.workdir/.gitignore @@ -0,0 +1,5 @@ +# This directory acts both as a cache so we can avoid constantly re-downloading +# the same protoc, and as a staging area where we can put a protoc-gen-go +# executable that won't interfere with the operation of other Go codebases +# on the same system which might want a different version of protoc-gen-go. +protoc-* diff --git a/tools/protobuf-compile/protobuf-compile.go b/tools/protobuf-compile/protobuf-compile.go new file mode 100644 index 0000000000..19cca308a2 --- /dev/null +++ b/tools/protobuf-compile/protobuf-compile.go @@ -0,0 +1,233 @@ +// protobuf-compile is a helper tool for running protoc against all of the +// .proto files in this repository using specific versions of protoc and +// protoc-gen-go, to ensure consistent results across all development +// environments. +// +// protoc itself isn't a Go tool, so we need to use a custom strategy to +// install and run it. The official releases are built only for a subset of +// platforms that Go can potentially target, so this tool will fail if you +// are using a platform other than the ones this wrapper tool has explicit +// support for. In that case you'll need to either run this tool on a supported +// platform or to recreate what it does manually using a protoc you've built +// and installed yourself. +package main + +import ( + "fmt" + "log" + "os" + "os/exec" + "path/filepath" + "runtime" + "strings" + + "github.com/hashicorp/go-getter" +) + +const protocVersion = "3.15.6" + +// We also use protoc-gen-go and its grpc addon, but since these are Go tools +// in Go modules our version selection for these comes from our top-level +// go.mod, as with all other Go dependencies. If you want to switch to a newer +// version of either tool then you can upgrade their modules in the usual way. +const protocGenGoPackage = "github.com/golang/protobuf/protoc-gen-go" +const protocGenGoGrpcPackage = "google.golang.org/grpc/cmd/protoc-gen-go-grpc" + +type protocStep struct { + DisplayName string + WorkDir string + Args []string +} + +var protocSteps = []protocStep{ + { + "tfplugin5 (provider wire protocol version 5)", + "internal/tfplugin5", + []string{"--go_out=paths=source_relative,plugins=grpc:.", "./tfplugin5.proto"}, + }, + { + "tfplugin6 (provider wire protocol version 6)", + "internal/tfplugin6", + []string{"--go_out=paths=source_relative,plugins=grpc:.", "./tfplugin6.proto"}, + }, + { + "tfplan (plan file serialization)", + "internal/plans/internal/planproto", + []string{"--go_out=paths=source_relative:.", "planfile.proto"}, + }, +} + +func main() { + if len(os.Args) != 2 { + log.Fatal("Usage: go run github.com/hashicorp/terraform/tools/protobuf-compile ") + } + baseDir := os.Args[1] + workDir := filepath.Join(baseDir, "tools/protobuf-compile/.workdir") + + protocLocalDir := filepath.Join(workDir, "protoc-v"+protocVersion) + if _, err := os.Stat(protocLocalDir); os.IsNotExist(err) { + err := downloadProtoc(protocVersion, protocLocalDir) + if err != nil { + log.Fatal(err) + } + } else { + log.Printf("already have protoc v%s in %s", protocVersion, protocLocalDir) + } + + protocExec := filepath.Join(protocLocalDir, "bin/protoc") + + protocGenGoExec, err := buildProtocGenGo(workDir) + if err != nil { + log.Fatal(err) + } + protocGenGoGrpcExec, err := buildProtocGenGoGrpc(workDir) + if err != nil { + log.Fatal(err) + } + + protocExec, err = filepath.Abs(protocExec) + if err != nil { + log.Fatal(err) + } + protocGenGoExec, err = filepath.Abs(protocGenGoExec) + if err != nil { + log.Fatal(err) + } + protocGenGoGrpcExec, err = filepath.Abs(protocGenGoExec) + if err != nil { + log.Fatal(err) + } + + // For all of our steps we'll run our localized protoc with our localized + // protoc-gen-go. + baseCmdLine := []string{protocExec, "--plugin=" + protocGenGoExec, "--plugin=" + protocGenGoGrpcExec} + + for _, step := range protocSteps { + log.Printf("working on %s", step.DisplayName) + + cmdLine := make([]string, 0, len(baseCmdLine)+len(step.Args)) + cmdLine = append(cmdLine, baseCmdLine...) + cmdLine = append(cmdLine, step.Args...) + + cmd := &exec.Cmd{ + Path: cmdLine[0], + Args: cmdLine[1:], + Dir: step.WorkDir, + Env: os.Environ(), + Stdout: os.Stdout, + Stderr: os.Stderr, + } + err := cmd.Run() + if err != nil { + log.Printf("failed to compile: %s", err) + } + } + +} + +// downloadProtoc downloads the given version of protoc into the given +// directory. +func downloadProtoc(version string, localDir string) error { + protocURL, err := protocDownloadURL(version) + if err != nil { + return err + } + + log.Printf("downloading and extracting protoc v%s from %s into %s", version, protocURL, localDir) + + // For convenience, we'll be using go-getter to actually download this + // thing, so we need to turn the real URL into the funny sort of pseudo-URL + // thing that go-getter wants. + goGetterURL := protocURL + "?archive=zip" + + err = getter.Get(localDir, goGetterURL) + if err != nil { + return fmt.Errorf("failed to download or extract the package: %s", err) + } + + return nil +} + +// buildProtocGenGo uses the Go toolchain to fetch the module containing +// protoc-gen-go and then build an executable into the working directory. +// +// If successful, it returns the location of the executable. +func buildProtocGenGo(workDir string) (string, error) { + exeSuffixRaw, err := exec.Command("go", "env", "GOEXE").Output() + if err != nil { + return "", fmt.Errorf("failed to determine executable suffix: %s", err) + } + exeSuffix := strings.TrimSpace(string(exeSuffixRaw)) + exePath := filepath.Join(workDir, "protoc-gen-go"+exeSuffix) + log.Printf("building %s as %s", protocGenGoPackage, exePath) + + cmd := exec.Command("go", "build", "-o", exePath, protocGenGoPackage) + cmd.Stdout = os.Stdout + cmd.Stderr = os.Stderr + err = cmd.Run() + if err != nil { + return "", fmt.Errorf("failed to build %s: %s", protocGenGoPackage, err) + } + + return exePath, nil +} + +// buildProtocGenGoGrpc uses the Go toolchain to fetch the module containing +// protoc-gen-go-grpc and then build an executable into the working directory. +// +// If successful, it returns the location of the executable. +func buildProtocGenGoGrpc(workDir string) (string, error) { + exeSuffixRaw, err := exec.Command("go", "env", "GOEXE").Output() + if err != nil { + return "", fmt.Errorf("failed to determine executable suffix: %s", err) + } + exeSuffix := strings.TrimSpace(string(exeSuffixRaw)) + exePath := filepath.Join(workDir, "protoc-gen-go-grpc"+exeSuffix) + log.Printf("building %s as %s", protocGenGoGrpcPackage, exePath) + + cmd := exec.Command("go", "build", "-o", exePath, protocGenGoGrpcPackage) + cmd.Stdout = os.Stdout + cmd.Stderr = os.Stderr + err = cmd.Run() + if err != nil { + return "", fmt.Errorf("failed to build %s: %s", protocGenGoGrpcPackage, err) + } + + return exePath, nil +} + +// protocDownloadURL returns the URL to try to download the protoc package +// for the current platform or an error if there's no known URL for the +// current platform. +func protocDownloadURL(version string) (string, error) { + platformKW := protocPlatform() + if platformKW == "" { + return "", fmt.Errorf("don't know where to find protoc for %s on %s", runtime.GOOS, runtime.GOARCH) + } + return fmt.Sprintf("https://github.com/protocolbuffers/protobuf/releases/download/v%s/protoc-%s-%s.zip", protocVersion, protocVersion, platformKW), nil +} + +// protocPlatform returns the package name substring for the current platform +// in the naming convention used by official protoc packages, or an empty +// string if we don't know how protoc packaging would describe current +// platform. +func protocPlatform() string { + goPlatform := runtime.GOOS + "_" + runtime.GOARCH + + switch goPlatform { + case "linux_amd64": + return "linux-x86_64" + case "linux_arm64": + return "linux-aarch_64" + case "darwin_amd64": + return "osx-x86_64" + case "darwin_arm64": + // As of 3.15.6 there isn't yet an osx-aarch_64 package available, + // so we'll install the x86_64 version and hope Rosetta can handle it. + return "osx-x86_64" + case "windows_amd64": + return "win64" // for some reason the windows packages don't have a CPU architecture part + default: + return "" + } +} diff --git a/tools/tools.go b/tools/tools.go index 1bee9f715c..e5e1255bab 100644 --- a/tools/tools.go +++ b/tools/tools.go @@ -5,7 +5,9 @@ package tools import ( _ "github.com/golang/mock/mockgen" + _ "github.com/golang/protobuf/protoc-gen-go" _ "github.com/mitchellh/gox" _ "golang.org/x/tools/cmd/cover" _ "golang.org/x/tools/cmd/stringer" + _ "google.golang.org/grpc/cmd/protoc-gen-go-grpc" )