π A command-line utility to export Protocol Buffers (proto) files to YAML, and JSON.
Currently supported exports are for:
- Packages
- Services
- RPCs
Supported filters are for:
- Options
We needed an intermediatate format to allow us to provision Service Level Objective resources using terraform.
The idea is to enumerate the associated protos and parse the export using a yamldecode()
or jsondecode()
function and prepolute our variables.
Addition features such as filtering and OpenSLO export formating coming.
proto2yaml
will export your .proto
files using the following format;
version: v0.0.5
packages:
- package: foo.service.profile.v1
services:
- service: ProfileAPI
rpc:
- name: GetProfiles
type: unary
- service: AdminAPI
rpc:
- name: CreateProfile
type: unary
- name: DeleteProfile
type: unary
- name: SyncProfile
type: server-streaming
Running proto2yaml
is availabile through several methods. You can using brew
, download it as a binary from GitHub releases, or running it as a distroless docker image.
Install brew and then run:
brew install krzko/tap/proto2yaml
Download the latest version from the Releases page.
Attach a bind mount to the source directory and the directory you want to export the file to.
To see all the tags view the Packages page.
To run the docker image follow these examples:
# Use current directory as source
docker run --rm \
-v "$(pwd)":/searchme \
ghcr.io/krzko/proto2yaml:latest yaml print --source /searchme
# Use an explicit path as source
docker run --rm \
-v "/Users/foobar/code/protos":/searchme \
ghcr.io/krzko/proto2yaml:latest yaml print --source /searchme
# Use an explicit path as source and current as export
docker run --rm \
-v "/Users/foobar/code/protos":/searchme \
-v "$(pwd)":/save \
ghcr.io/krzko/proto2yaml:latest yaml print --source /searchme --file /save/example_protos.yaml
NAME:
proto2yaml - A command-line utility to convert Protocol Buffers (proto) files to YAML
USAGE:
proto2yaml [global options] command [command options] [arguments...]
VERSION:
proto2yaml version v0.0.6-9ad396c (2022-07-21T05:33:05Z)
COMMANDS:
json The outputs are formatted as JSON
yaml The outputs are formatted as YAML
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--help, -h show help (default: false)
--version, -v print the version (default: false)
To export to a file, run the following command
# JSON
proto2yaml json export --source ./protos --file ./example_protos.json
# JSON pretty
proto2yaml json export --source ./protos --file ./example_protos.json --pretty
# YAML
proto2yaml yaml export --source ./protos --file ./example_protos.yaml
To filter on an option
you can use the --exclude-option
or --include-option
filter. For now its based on singletons but hope to expand out multiple combinations in the future. An example is as follows:
proto2yaml yaml print --source ./protos --exclude-option "deprecated=true"
Or run the inverse of the above using:
proto2yaml yaml print --source ./protos --include-option "deprecated=true"
To print to the console, clone the repo and run the following command:
# JSON
proto2yaml json print --source ./protos
# JSON pretty
proto2yaml json print --source ./protos --pretty
# YAML
proto2yaml yaml print --source ./protos
If you need to run the tool in your CI/CD pipelines and ANSI isn't supported, you can pass the following variable to disable colour:
export NO_COLOR="true"
To enable colour again, simply unset
the variable:
unset NO_COLOR
To build to the binaries use the following targets. All outputs are generated to the bin
directory.
To build all the the targets, simply run:
# Default target invoked
make
# Explicit target
make build
To run all the builds without Docker, simply run:
make build-no-docker
The following targets will generate your Linux binaries:
make build-linux
macOS has two targets, one for the older Intel amd64
CPUs and one for the newer Mx arm64
CPUs. The following targets will generate your binaries:
# For intel macs
make build-darwin-amd64
# For m1 macs
make build-darwin-arm64
The following targets will generate your Windows executable:
make build-windows
The general make build
and back-build-no-docker
targets will also build Raspberry Pi and FreeBSD version, along with a distroless Docker image, if selected.