update readme (#9)

* update readme
* changelog
* update makefile
* dep ensure

Gopkg.toml

@@ -6,10 +6,6 @@
   name = "gopkg.in/fsnotify.v1"
   source = "https://github.com/fsnotify/fsnotify.git"
 
-[[constraint]]
-  name = "github.com/solo-io/go-utils"
-  version = "=v0.9.17"
-
 [[constraint]]
   name = "github.com/solo-io/ext-auth-plugins"
   version = "=v0.1.0"
@@ -30,10 +26,6 @@
   name = "go.uber.org/atomic"
   version = "=v1.3.2"
 
-[[override]]
-  name = "github.com/golang/protobuf"
-  version = "=v1.2.0"
-
 [[override]]
   name = "gopkg.in/tomb.v1"
   revision = "c131134a1947e9afd9cecfe11f4c6dff0732ae58"
@@ -46,10 +38,6 @@
   name = "github.com/onsi/ginkgo"
   version = "=v1.7.0"
 
-[[override]]
-  name = "github.com/onsi/gomega"
-  version = "=v1.4.3"
-
 [[override]]
   name = "gopkg.in/yaml.v2"
   version = "=v2.2.1"
@@ -66,10 +54,6 @@
   name = "github.com/pelletier/go-toml"
   version = "=v1.2.0"
 
-[[override]]
-  name = "google.golang.org/genproto"
-  revision = "02b4e95473316948020af0b7a4f0f22c73929b0e"
-
 [[override]]
   name = "golang.org/x/sys"
   revision = "ac767d655b305d4e9612f5f6e33120b9176c4ad4"
@@ -80,4 +64,30 @@
 
 [[override]]
   name = "golang.org/x/text"
-  revision = "f21a4dfb5e38f5895301dc265a8def02365cc3d0"
+  revision = "f21a4dfb5e38f5895301dc265a8def02365cc3d0"
+
+
+[[override]]
+  name = "github.com/solo-io/go-utils"
+  revision = "c4b31e48e70d441b0f085d0a9cbd981ae620e0c7"
+
+
+[[override]]
+  name = "github.com/golang/protobuf"
+  revision = "6c65a5562fc06764971b7c5d05c76c75e84bdbf7"
+
+
+[[override]]
+  name = "github.com/onsi/gomega"
+  revision = "bdebf9e0ece900259084cfa4121b97ce1a540939"
+
+
+[[override]]
+  name = "google.golang.org/genproto"
+  revision = "548a555dbc03994223efbaba0090152849259498"
+
+
+[[override]]
+  name = "github.com/gogo/protobuf"
+  revision = "0ca988a254f991240804bf9821f3450d87ccbb1b"
+

Makefile

@@ -10,7 +10,7 @@ GLOOE_DIR := _glooe
 _ := $(shell mkdir -p $(GLOOE_DIR))
 
 # Set this variable to the version of GlooE you want to target
-GLOOE_VERSION ?= 0.18.21
+GLOOE_VERSION ?= 1.0.0-rc2
 
 .PHONY: get-glooe-info
 get-glooe-info: $(GLOOE_DIR)/Gopkg.lock $(GLOOE_DIR)/verify-plugins-linux-amd64 $(GLOOE_DIR)/build_env
@@ -56,4 +56,7 @@ build-plugins: $(GLOOE_DIR)/build_env $(GLOOE_DIR)/verify-plugins-linux-amd64
 build-plugins-for-tests: $(EXAMPLES_DIR)/required_header/RequiredHeader.so
 
 $(EXAMPLES_DIR)/required_header/RequiredHeader.so: $(SOURCES)
-	go build -buildmode=plugin -o $(EXAMPLES_DIR)/required_header/RequiredHeader.so $(EXAMPLES_DIR)/required_header/plugin.go
+	go build -buildmode=plugin -o $(EXAMPLES_DIR)/required_header/RequiredHeader.so $(EXAMPLES_DIR)/required_header/plugin.go
+
+clean:
+	rm -rf _glooe

README.md

@@ -55,3 +55,75 @@ where the tag `glooe_version` is the version of GlooE you want to run the plugin
 ## Publishing your own plugins
 To publish your own images you can just tag the image built in the `build-plugins` target (by adding add a `-t` option) 
 and publish it to a docker registry that is reachable from the cluster you are running GlooE in.
+
+# Example workflow
+
+Note: these instructions work on gloo-e <= 1.0.0-rc2
+In gloo-e 1.0.0-rc3, we transitioned to using go modules for dependency managment. We will update 
+these instructions soon for versions of gloo-e >= 1.0.0-rc3.
+
+First, set your gloo-e version to an environment variable:
+```
+export GLOOE_VERSION=1.0.0-rc2
+```
+
+Run `compare-deps` to check if gloo and your plugin have different dependencies:
+
+```
+make GLOOE_VERSION=$GLOOE_VERSION compare-deps
+```
+
+If there are any mismatched dependencies, A file named `overrides.toml` will be created. Please 
+reconcile the contents of this file with your `Gopkg.toml`. This means replacing existing entries,
+and adding missing entries.
+
+Once the `Gopkg.toml` is up to date, run `dep ensure` to update your vendor folder:
+
+```
+dep ensure
+```
+
+Build the plugins using the `build-plugins` make target.
+It is important to build the plugins using the Makefile as this will build them in a docker container
+in such a way that they are compatible with gloo. This step will also verify that they can be loaded.
+
+```
+make GLOOE_VERSION=$GLOOE_VERSION build-plugins
+```
+
+This will build an anonymous container with the plugin for you. The output will look like so:
+```
+...
+ ---> 4846ae5e0a4d
+Step 15/16 : COPY --from=build-env /go/src/github.com/solo-io/ext-auth-plugin-examples/plugins/RequiredHeader.so /compiled-auth-plugins/
+ ---> 1932dbdca716
+Step 16/16 : CMD cp /compiled-auth-plugins/* /auth-plugins/
+ ---> Running in c33580aff7e1
+Removing intermediate container c33580aff7e1
+ ---> c6d2a92c47e4
+Successfully built c6d2a92c47e4
+```
+Specifically note the `Successfully built c6d2a92c47e4` line.
+In our case `c6d2a92c47e4` is the ID of the container just built.
+To push this container, first re-tag it with your docker registry:
+
+```
+docker tag c6d2a92c47e4 username/dockerrepo:v1
+```
+
+And push it:
+
+```
+docker push username/dockerrepo:v1
+```
+
+You can now use this plugin as an init container for gloo's extauth module.
+
+## Common Errors
+
+If you see this error in the json log:
+```
+{"level":"error","ts":"2019-12-17T20:59:17.301Z","logger":"verify-plugins","caller":"scripts/verify_plugins.go:54","msg":"Plugin(s) cannot be loaded by Gloo","error":"failed to load plugin: failed to open plugin file: plugin.Open(\"plugins/RequiredHeader\"): plugin was built with a different version of package github.com/golang/protobuf/proto","errorVerbose":"failed to load plugin:\n    github.com/solo-io/go-utils/errors.Wrapf\n        /go/src/github.com/solo-io/go-utils/errors/utils.go:12\n  - failed to open plugin file:\n    github.com/solo-io/go-utils/errors.Wrapf\n        /go/src/github.com/solo-io/go-utils/errors/utils.go:12\n  - plugin.Open(\"plugins/RequiredHeader\"): plugin was built with a different version of package github.com/golang/protobuf/proto","stacktrace":"main.main\n\t/go/src/github.com/solo-io/solo-projects/projects/extauth/scripts/verify_plugins.go:54\nruntime.main\n\t/usr/local/go/src/runtime/proc.go:200"}
+```
+
+Make sure that the Gopkg.toml has the right deps from the `overrides.toml` file and that you have run `dep ensure`

changelog/v0.1.1/updated-readme.yaml

@@ -0,0 +1,3 @@
+changelog:
+- type: NON_USER_FACING
+  description: Updated readme.

plugins/plugin_manifest.yaml

@@ -1,10 +1,9 @@
-plugins:
-- name: RequiredHeader
-  pluginFileName: RequiredHeader.so
-  exportedSymbolName: Plugin
-  config:
-    RequiredHeader: my-auth-header
-    AllowedValues:
-    - foo
-    - bar
-    - baz
+name: RequiredHeader
+pluginFileName: RequiredHeader.so
+exportedSymbolName: Plugin
+config:
+  RequiredHeader: my-auth-header
+  AllowedValues:
+  - foo
+  - bar
+  - baz

scripts/compare_dependencies.go

@@ -11,6 +11,7 @@ import (
 )
 
 const errorReportFile = "mismatched_dependencies.json"
+const overridesFile = "overrides.toml"
 
 type depProjects map[string]dependencyInfo
 
@@ -100,6 +101,25 @@ func main() {
 	if err := ioutil.WriteFile(errorReportFile, reportBytes, 0644); err != nil {
 		fmt.Printf("Failed to write error report file: %s/n", err.Error())
 	}
+
+	overrideFile, err := os.Create(overridesFile)
+	if err == nil {
+		for _, pair := range nonMatchingDeps {
+
+			fmt.Fprintf(overrideFile,
+				`
+[[override]]
+  name = "%s"
+  revision = "%s"
+
+`, pair.GlooE.Name, pair.GlooE.Revision)
+
+		}
+		overrideFile.Close()
+	}
+
+	fmt.Printf("Writing overrides file [%s], please reconcile that with yout Gopkg.toml file\n", overridesFile)
+
 	os.Exit(1)
 }