finalize v1.1.0-beta1 (#418)

* doc / conf updates and tests per 1.1 enhancements * relocate systemd file, rename helm readme file * linting * update helm readme * streamline release tarball layout * add span descriptions to tracing docs * add docker-compose demo * add new/changed v1.1 doc
trickstercache · May 5, 2020 · e0d9703 · e0d9703
1 parent bf7c100
commit e0d9703
Show file tree

Hide file tree

Showing 55 changed files with 2,918 additions and 325 deletions.
diff --git a/.gitignore b/.gitignore
@@ -7,6 +7,8 @@
 # Test binary, build with `go test -c`
 *.test
 .coverprofile
+prometheus-data
+trickster-data
 
 # Output of the go coverage tool, specifically when used with LiteIDE
 *.out

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -29,28 +29,27 @@ If you find a bug in Trickster, please file a detailed report as an Issue. We cu
 
 Likewise, if you have a Feature Request, please file a detailed Issue, explaining the feature's functionality and use cases. Features should be useful to the broader community, so be sure to consider that before filing.
 
-If you find a security vulnerability in Trickster, please report it at https://my.xfinity.com/vulnerabilityreport and contact the [Maintainers](MAINTAINERS.md).
+If you find a security vulnerability in Trickster, please report it at <https://my.xfinity.com/vulnerabilityreport> and contact the [Maintainers](MAINTAINERS.md).
 
 ## Steps to Contribute
 
-
 Should you wish to work on an issue, please claim it first by commenting on the GitHub issue that you want to work on it. This is to prevent duplicated efforts from contributors on the same issue.
 
 If you have questions about one of the issues, please comment on them and one of the maintainers will clarify it. For a quicker response, contact us on the #trickster slack channel.
 
 For complete instructions on how to compile see: [Building From Source](https://github.com/tricksterproxy/trickster#building-from-source)
 
 For quickly compiling and testing your changes do:
-```
+
+```bash
 # For building.
 make
-./trickster
+./OPATH/trickster
 
 # For testing.
 make test
 ```
 
-
 ## Pull Request Checklist
 
 * Branch from the master branch and, if needed, rebase to the current master branch before submitting your pull request. If it doesn't merge cleanly with master you may be asked to rebase your changes.

diff --git a/Makefile b/Makefile
@@ -11,6 +11,7 @@
 
 DEFAULT: build
 
+PROJECT_DIR    := $(shell pwd)
 GO             ?= go
 GOFMT          ?= $(GO)fmt
 FIRST_GOPATH   := $(firstword $(subst :, ,$(shell $(GO) env GOPATH)))
@@ -24,7 +25,11 @@ IMAGE_TAG      ?= latest
 IMAGE_ARCH     ?= amd64
 GOARCH         ?= amd64
 TAGVER         ?= unspecified
-LDFLAGS         =-ldflags "-s -X main.applicationBuildTime=$(BUILD_TIME) -X main.applicationGitCommitID=$(GIT_LATEST_COMMIT_ID) -X main.applicationGoVersion=$(GO_VER) -X main.applicationGoArch=$(GOARCH)"
+LDFLAGS         =-ldflags "-extldflags '-static' -w -s -X main.applicationBuildTime=$(BUILD_TIME) -X main.applicationGitCommitID=$(GIT_LATEST_COMMIT_ID) -X main.applicationGoVersion=$(GO_VER) -X main.applicationGoArch=$(GOARCH)"
+BUILD_SUBDIR   := OPATH
+PACKAGE_DIR    := ./$(BUILD_SUBDIR)/trickster-$(PROGVER)
+BIN_DIR        := $(PACKAGE_DIR)/bin
+CONF_DIR       := $(PACKAGE_DIR)/conf
 
 .PHONY: validate-app-version
 validate-app-version:
@@ -46,16 +51,16 @@ test-go-mod:
 
 .PHONY: build
 build:
-	GOOS=$(GOOS) GOARCH=$(GOARCH) CGO_ENABLED=$(CGO_ENABLED) $(GO) build $(LDFLAGS) -o ./OPATH/trickster -a -v $(TRICKSTER_MAIN)/*.go
+	GOOS=$(GOOS) GOARCH=$(GOARCH) CGO_ENABLED=$(CGO_ENABLED) $(GO) build $(LDFLAGS) -o ./$(BUILD_SUBDIR)/trickster -a -v $(TRICKSTER_MAIN)/*.go
 
 rpm: build
-	mkdir -p ./OPATH/SOURCES
-	cp -p ./OPATH/trickster ./OPATH/SOURCES/
-	cp $(TRICKSTER_MAIN)/conf/trickster.service ./OPATH/SOURCES/
+	mkdir -p ./$(BUILD_SUBDIR)/SOURCES
+	cp -p ./$(BUILD_SUBDIR)/trickster ./$(BUILD_SUBDIR)/SOURCES/
+	cp $(TRICKSTER_MAIN)/conf/trickster.service ./$(BUILD_SUBDIR)/SOURCES/
 	sed -e 's%^# log_file =.*$$%log_file = "/var/log/trickster/trickster.log"%' \
 		-e 's%prometheus:9090%localhost:9090%' \
-		< $(TRICKSTER_MAIN)/conf/example.conf > ./OPATH/SOURCES/trickster.conf
-	rpmbuild --define "_topdir $(CURDIR)/OPATH" \
+		< $(TRICKSTER_MAIN)/conf/example.conf > ./$(BUILD_SUBDIR)/SOURCES/trickster.conf
+	rpmbuild --define "_topdir $(CURDIR)/$(BUILD_SUBDIR)" \
 		--define "_version $(PROGVER)" \
 		--define "_release 1" \
 		-ba deploy/packaging/trickster.spec
@@ -68,11 +73,25 @@ install:
 release: validate-app-version clean go-mod-tidy go-mod-vendor release-artifacts
 
 .PHONY: release-artifacts
-release-artifacts:
-	GOOS=darwin   GOARCH=amd64 $(GO) build $(LDFLAGS) -o ./OPATH/trickster-$(PROGVER).darwin-amd64       -a -v $(TRICKSTER_MAIN)/*.go && tar cvfz ./OPATH/trickster-$(PROGVER).darwin-amd64.tar.gz  ./OPATH/trickster-$(PROGVER).darwin-amd64
-	GOOS=linux    GOARCH=amd64 $(GO) build $(LDFLAGS) -o ./OPATH/trickster-$(PROGVER).linux-amd64        -a -v $(TRICKSTER_MAIN)/*.go && tar cvfz ./OPATH/trickster-$(PROGVER).linux-amd64.tar.gz   ./OPATH/trickster-$(PROGVER).linux-amd64
-	GOOS=linux    GOARCH=arm64 $(GO) build $(LDFLAGS) -o ./OPATH/trickster-$(PROGVER).linux-arm64        -a -v $(TRICKSTER_MAIN)/*.go && tar cvfz ./OPATH/trickster-$(PROGVER).linux-arm64.tar.gz   ./OPATH/trickster-$(PROGVER).linux-arm64
-	GOOS=windows  GOARCH=amd64 $(GO) build $(LDFLAGS) -o ./OPATH/trickster-$(PROGVER).windows-amd64.exe  -a -v $(TRICKSTER_MAIN)/*.go && tar cvfz ./OPATH/trickster-$(PROGVER).windows-amd64.tar.gz ./OPATH/trickster-$(PROGVER).windows-amd64.exe
+release-artifacts: clean
+
+	mkdir -p $(PACKAGE_DIR)
+	mkdir -p $(BIN_DIR)
+	mkdir -p $(CONF_DIR)
+
+	cp -r ./docs $(PACKAGE_DIR)
+	cp -r ./deploy $(PACKAGE_DIR)
+	cp ./README.md $(PACKAGE_DIR)
+	cp ./CONTRIBUTING.md $(PACKAGE_DIR)
+	cp ./LICENSE $(PACKAGE_DIR)
+	cp ./cmd/trickster/conf/*.conf $(CONF_DIR)
+
+	GOOS=darwin  GOARCH=amd64 $(GO) build $(LDFLAGS) -o $(BIN_DIR)/trickster-$(PROGVER).darwin-amd64  -a -v $(TRICKSTER_MAIN)/*.go
+	GOOS=linux   GOARCH=amd64 $(GO) build $(LDFLAGS) -o $(BIN_DIR)/trickster-$(PROGVER).linux-amd64   -a -v $(TRICKSTER_MAIN)/*.go
+	GOOS=linux   GOARCH=arm64 $(GO) build $(LDFLAGS) -o $(BIN_DIR)/trickster-$(PROGVER).linux-arm64   -a -v $(TRICKSTER_MAIN)/*.go
+	GOOS=windows GOARCH=amd64 $(GO) build $(LDFLAGS) -o $(BIN_DIR)/trickster-$(PROGVER).windows-amd64 -a -v $(TRICKSTER_MAIN)/*.go
+
+	cd ./$(BUILD_SUBDIR) && tar cvfz ./trickster-$(PROGVER).tar.gz ./trickster-$(PROGVER)/*
 
 # Minikube and helm bootstrapping are done via deploy/helm/Makefile
 .PHONY: helm-local
@@ -123,4 +142,4 @@ test-cover: test
 
 .PHONY: clean
 clean:
-	rm -rf ./trickster ./OPATH
+	rm -rf ./trickster ./$(BUILD_SUBDIR)
diff --git a/README.md b/README.md
@@ -67,7 +67,11 @@ Trickster's Fast Forward feature ensures that even with step boundary normalizat
 
 <img src="./docs/images/fast-forward.png" width=640 />
 
-## Install
+## Trying Out Trickster
+
+Check out our end-to-end [Docker Compose demo composition](./deploy/trickster-demo) for a zero-configuration running environment.
+
+## Installing
 
 ### Docker
 
@@ -77,9 +81,13 @@ Docker images are available on Docker Hub:
 
 See the 'deploy' Directory for more information about using or creating Trickster docker images.
 
-### Kubernetes and Helm
+### Kubernetes
+
+See the 'deploy' Directory for Kube and deployment files and examples.
+
+### Helm
 
-See the 'deploy' Directory for both Kube and Helm deployment files and examples.
+Trickster Helm Charts are located at <https://helm.tricksterproxy.io> for installation, and maintained at <https://github.com/tricksterproxy/helm-charts>. We welcome chart contributions.
 
 ### Building from source
 

diff --git a/cmd/trickster/conf/example.conf b/cmd/trickster/conf/example.conf
@@ -5,7 +5,7 @@
 #
 # This file contains descriptions and examples for all
 # Trickster configuration options. More documentation is
-# available at https://github.com/Comcast/trickster/docs/
+# available at https://github.com/tricksterproxy/trickster/docs/
 #
 # Optional configs are commented out, required configs are uncommented
 # and set to common values that let you try it out with Prometheus
@@ -30,6 +30,9 @@
 ## default is '/trickster/ping'
 # ping_handler_path = '/trickster/ping'
 
+## pprof_server provides the name of the http listener that will host the pprof debugging routes
+## Options are: "metrics", "reload", "both", or "off"; default is both
+# pprof_server = 'both'
 
 # Configuration options for the Trickster Frontend
 [frontend]
@@ -243,15 +246,15 @@ listen_port = 8480
     # origin_type is a required configuration value
     origin_type = 'prometheus'
 
+    # origin_url provides the base upstream URL for all proxied requests to this origin.
+    # it can be as simple as http://example.com or as complex as https://example.com:8443/path/prefix
+    # origin_url is a required configuration value
+    origin_url = 'http://prometheus:9090'
+
     ## is_default describes whether this origin is the default origin considered when routing http requests
     ## it is false, by default; but if you only have a single origin configured, is_default will be true unless explicitly set to false
     # is_default = true
 
-    ## path_routing_disabled will prevent the origin from being accessible via /origin_name/ path to Trickster. Disabling this requires
-    ## the origin to have hosts configured (see below) or be the target of a rule origin, or it will be unreachable.
-    ## default is false
-    # path_routing_disabled = false
-
     ## hosts indicates which FQDNs requested by the client should route to this Origin (in addition to path-based routing)
     ## if you are using TLS, all FQDNs should be included in the certfiicate common names to avoid insecure warnings to clients
     ## default setting is empty list. List format is: hosts = [ '1.example.com', '2.example.com' ]
@@ -267,10 +270,18 @@ listen_port = 8480
     ## negative_cache_name identifies the name of the negative cache (configured above) to be used with this origin. default is 'default'
     # negative_cache_name = 'default'
 
-	# origin_url provides the base upstream URL for all proxied requests to this origin.
-	# it can be as simple as http://example.com or as complex as https://example.com:8443/path/prefix
-    # origin_url is a required configuration value
-    origin_url = 'http://prometheus:9090'
+    ## path_routing_disabled will prevent the origin from being accessible via /origin_name/ path to Trickster. Disabling this requires
+    ## the origin to have hosts configured (see below) or be the target of a rule origin, or it will be unreachable.
+    ## default is false
+    # path_routing_disabled = false
+
+    ## rule_name provides the name of the rule config to be used by this origin.
+    ## This is only effective if the origin_type is 'rule'
+    # rule_name = 'example-rule'
+
+    ## req_rewriter_name is the name of a configured rewriter (in [request_rewriters]) that will modify the request prior to
+    ## processing by the origin client
+    # req_rewriter_name = 'example-rewriter'
 
     ## tracing_name selects the distributed tracing configuration (crafted below) to be used with this origin. default is 'default'
     # tracing_name = 'default'
@@ -365,13 +376,15 @@ listen_port = 8480
                 # [origins.default.paths.example1.response_headers] 
                 # 'Cache-Control' = 'no-cache'                  # attach these headers to the response down to the client
                 # 'Content-Type' = 'text/plain'
-
             # [origins.default.paths.example2]
             # path = '/example/'
             # methods = [ 'GET', 'POST' ]
-            # collapsed_forwarding = 'progressive'                  # see /docs/collapsed_forwarding.md
-            # match_type = 'prefix'                                 # this path is routed using prefix matching
-            # handler = 'proxycache'                                # this path is routed through the cache
+            # collapsed_forwarding = 'progressive'    # see /docs/collapsed_forwarding.md
+            # match_type = 'prefix'                   # this path is routed using prefix matching
+            # handler = 'proxycache'                  # this path is routed through the cache
+            # req_rewriter_name = 'example-rewriter'  # name of a rewriter to modify the request prior to handling
+
+
             # cache_key_params = [ 'ex_param1', 'ex_param2' ]       # the cache key will be hashed with these query parameters (GET)
             # cache_key_form_fields = [ 'ex_param1', 'ex_param2' ]  # or these form fields (POST)
             # cache_key_headers = [ 'X-Example-Header' ]            # and these request headers, when present in the incoming request
@@ -445,10 +458,24 @@ listen_port = 8480
 #   input_delimiter = ' '
 #   operation = 'prefix'              # check the input value matches any of the defined cases:
 #   next_route = 'reader-cluster' # by default, route to reader-cluster origin (would need to be defined)
-# 	[rules.example.cases]
-# 		[rules.example.cases.1]
-# 		matches = ['johndoe:', 'janedoe:']  # if the Authorization header has user johndoe or janedoe,
-# 		next_route = 'writer-cluster'       # route the request to hypothetical writer-cluster origin
+#     [rules.example.cases]
+#       [rules.example.cases.1]
+#       matches = ['johndoe:', 'janedoe:']  # if the Authorization header has user johndoe or janedoe,
+#       next_route = 'writer-cluster'       # route the request to hypothetical writer-cluster origin
+##
+##    Other available case configs that are not pertinent to this example:
+#     req_rewriter_name = ''      # name of a rewriter to process the request if it matches this case
+#                                 # case rewrites are executed prior to giving control back to the rule
+#     redirect_url = ''  # provides a URL to redirect the request if it matches this case
+##
+##  Other available rule configs that are not pertinent to this example:
+#   ingress_req_rewriter_name = '' # name of a rewriter to process the request before evaluating the rule
+#   egress_req_rewriter_name = ''  # name of a rewriter to process the request after evaluating the rule
+##                                 # and handing off to the new route
+#   nomatch_req_rewriter_name = '' # name of a rewriter to run the request through when there are no matching cases
+#   operation_arg = '' # an argument to pass to the operation.
+#   redirect_url = '' # provides a URL to redirect the request in the default case, rather than handing to next_route
+#   max_rule_executions = 16        # limits the max number of per-Request rule-based hops to avoid execution loops.
 
 ## Configuration Options for Request Rewriter Instructions - see /docs/request_rewriters.md for more info
 #
@@ -466,17 +493,17 @@ listen_port = 8480
     ## to origins by the 'tracing_name' value in origin configs, which, by default, use 'default'
     # [tracing.default]
 
-    ## tracer_type specifies the type backend tracing system where traces are sent
+    ## tracer_type specifies the type of backend tracing system where traces are sent (in that format)
     ## options are: jaeger, zipkin, stdout or none.  none is the default
     # tracer_type = 'none'
 
-    ## service_name specifies the service.name tag/attribute value included in traces
+    ## service_name specifies the service name under which the traces are registered by this tracer
     ## default is 'trickster'
     # service_name = 'trickster'
 
     ## collector_url is the URL of the tracing backend
     ## required for zipkin and jaeger, unused for stdout
-    # collector_url = ''
+    # collector_url = 'http://jaeger:14268/api/traces'
 
     ## collector_user is the username credential for authenticating with the tracing backend
     ## optional jaeger; unused for zipkin and stdout
@@ -486,13 +513,14 @@ listen_port = 8480
     ## optional jaeger; unused for zipkin and stdout
     # collector_pass = ''
 
-	## sample_rate sets the probability that a span will be recorded.
-	## A floating point value of 0.0 to 1.0 (inclusive) is permitted
+    ## sample_rate sets the probability that a span will be recorded.
+    ## A floating point value of 0.0 to 1.0 (inclusive) is permitted
     ## default is 1.0 (meaning 100% of requests are recorded)
-	# sample_rate = 1.0
+    # sample_rate = 1.0
 
       ## tags will append these tags/attributes to each trace that is recorded
       ## only string key/value tags are supported. numeric values, etc are not.
+      ## For Jaeger, these key/values are added to the "Process" section
       ## default tags list is empty
       # [tracing.default.tags]
       # key1 = "value1"
@@ -513,16 +541,16 @@ listen_port = 8480
     ## another example tracing config named 'example' using jaeger agent backend and a 50% sample rate
     # [tracing.example]
     # tracer_type = 'jaeger'
-    # collector_url = 'https://jaeger.example.com/'
-	# sample_rate = .5
+    # collector_url = 'http://jaeger:14268/api/traces'
+    # sample_rate = .5
     #   [tracing.example.jaeger]
     #   endpoint_type = 'agent'
 
     ## another example tracing config named 'zipkin-example' using zipkin backend and a 10% sample rate
     # [tracing.zipkin-example]
     # tracer_type = 'zipkin'
     # collector_url = 'https://zipkin.example.com/'
-	# sample_rate = .1
+    # sample_rate = .1
 
 
 ## Configuration Options for Metrics Instrumentation

diff --git a/cmd/trickster/conf/simple.prometheus.conf b/cmd/trickster/conf/simple.prometheus.conf
@@ -5,7 +5,7 @@
 #
 # This file demonstrates a basic configuration to accelerate
 # Prometheus queries using Trickster. More documentation is
-# available at https://github.com/Comcast/trickster/docs/
+# available at https://github.com/tricksterproxy/trickster/docs/
 #
 # Copyright 2018 Comcast Cable Communications Management, LLC
 #

diff --git a/cmd/trickster/conf/simple.reverseproxycache.conf b/cmd/trickster/conf/simple.reverseproxycache.conf
@@ -5,7 +5,7 @@
 #
 # This file demonstrates a basic configuration for operating an
 # HTTP Reverse Proxy Cache using Trickster. More documentation is
-# available at https://github.com/Comcast/trickster/docs/
+# available at https://github.com/tricksterproxy/trickster/docs/
 #
 # Copyright 2018 Comcast Cable Communications Management, LLC
 #

diff --git a/cmd/trickster/config.go b/cmd/trickster/config.go
@@ -102,7 +102,7 @@ func applyConfig(conf, oldConf *config.Config, wg *sync.WaitGroup, log *log.Logg
 	}
 
 	//Register Tracing Configurations
-	tracers, err := tr.RegisterAll(conf, log)
+	tracers, err := tr.RegisterAll(conf, log, false)
 	if err != nil {
 		handleStartupIssue("tracing registration failed", tl.Pairs{"detail": err.Error()},
 			log, errorsFatal)
@@ -280,7 +280,7 @@ func validateConfig(conf *config.Config) error {
 	router := mux.NewRouter()
 	log := log.ConsoleLogger(conf.Logging.LogLevel)
 
-	tracers, err := tr.RegisterAll(conf, log)
+	tracers, err := tr.RegisterAll(conf, log, true)
 	if err != nil {
 		return err
 	}

diff --git a/deploy/Dockerfile b/deploy/Dockerfile
@@ -1,16 +1,16 @@
 ARG IMAGE_ARCH=amd64
 
-FROM golang:1.14.1 as builder
-COPY . /go/src/github.com/Comcast/trickster
-WORKDIR /go/src/github.com/Comcast/trickster
+FROM golang:1.14.2 as builder
+COPY . /go/src/github.com/tricksterproxy/trickster
+WORKDIR /go/src/github.com/tricksterproxy/trickster
 
 ARG GOARCH=amd64
 RUN GOOS=linux GOARCH=${GOARCH} CGO_ENABLED=0 make build
 
 FROM ${IMAGE_ARCH}/alpine:3.11.5
 LABEL maintainer "The Trickster Authors <[email protected]>"
 
-COPY --from=builder /go/src/github.com/Comcast/trickster/OPATH/trickster /usr/local/bin/trickster
+COPY --from=builder /go/src/github.com/tricksterproxy/trickster/OPATH/trickster /usr/local/bin/trickster
 COPY cmd/trickster/conf/example.conf /etc/trickster/trickster.conf
 RUN chown nobody /usr/local/bin/trickster
 RUN chmod +x /usr/local/bin/trickster

diff --git a/deploy/helm/README.md b/deploy/helm/README.md
@@ -0,0 +1,5 @@
+# Helm Charts
+
+Trickster's Helm charts are located in their own project at <https://github.com/tricksterproxy/helm-charts/>. We welcome contributions to our charts.
+
+If you want to Install the Trickster charts, see <https://helm.tricksterproxy.io/> or search for Trickster on Helm Hub.
diff --git a/deploy/helm/moved.md b/deploy/helm/moved.md