docs: add "Building" "Running the plugin Locally" "Making releases" i… (

#50) * docs: add "Building" "Running the plugin Locally" "Making releases" in contributing page Signed-off-by: Philipp Plotnikov <[email protected]> * docs: back warning to the contributing page Signed-off-by: Philipp Plotnikov <[email protected]> * fix: update gateway api version Signed-off-by: Philipp Plotnikov <[email protected]> * docs: remove Running E2E tests header Signed-off-by: Philipp Plotnikov <[email protected]> * docs: add Argo Rollouts plugin system architecture Signed-off-by: Philipp Plotnikov <[email protected]> * fix: fix unit tests Signed-off-by: Philipp Plotnikov <[email protected]> * refactor: linting Signed-off-by: Philipp Plotnikov <[email protected]> * docs: fix ordered list Building section Signed-off-by: Philipp Plotnikov <[email protected]> * docs: small addition about the namespace of argo-rollouts-config config map Signed-off-by: Philipp Plotnikov <[email protected]> --------- Signed-off-by: Philipp Plotnikov <[email protected]>
argoproj-labs · Apr 26, 2024 · b2477b9 · b2477b9
1 parent b30ce3e
commit b2477b9
Show file tree

Hide file tree

Showing 13 changed files with 227 additions and 208 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -7,7 +7,7 @@ on:
  branches:
  - "main"
 env:
- GOLANG_VERSION: '1.20'
+ GOLANG_VERSION: '1.22'
 
 jobs:
  unit-tests:

diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
@@ -6,7 +6,7 @@ on:
  - "release-v[0-9]+.[0-9]+.[0-9]+-rc[0-9]+"
 
 env:
- GOLANG_VERSION: "1.20"
+ GOLANG_VERSION: "1.22"
 
 jobs:
  release-creation:

diff --git a/Makefile b/Makefile
@@ -21,8 +21,9 @@ local-build:
 lint:
  golangci-lint run --fix
 
-
-
+.PHONY: test
+test:
+ go test -v ./...
 
 # convenience target to run `mkdocs serve` using a docker container
 .PHONY: serve-docs

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -24,35 +24,67 @@ git clone https://github.com/argoproj-labs/rollouts-plugin-trafficrouter-gateway
 cd rollouts-plugin-trafficrouter-gatewayapi
 ```
 
-## Building
+## Argo Rollouts plugin system architecture
 
-`go.mod` is used, so the `go build/test` commands automatically install the needed dependencies
+When Argo Rollouts controller starts, it requests the ConfigMap **argo-rollouts-config** (from the namespace in which controller is located) from api server of k8s cluster and if it gets it, it validates its content before putting this ConfigMap in RAM. It is important to understand it happens only at the beginning and only one time, so if you will change **argo-rollouts-config** or you will add it after Argo Rollouts controller you will need to restart Argo Rollouts. Controller uses this config map to understand where specified in argo manifest plugins are. When Argo Rollouts learns their locations it downloads and executes them as seperate RPC servers in the same pod. When controller gets specific events, for example events corresponding to the SetWeight action, it makes specific remote procedure call to the needing RPC server and waits its response. Diagram illustrating the main aspects of architecture is below
+
+![Argo rollouts plugin system architecture](./images/contributing/argo-rollouts-plugin-system-architecture.png)
+
+
+## Project dependecies
 
-The `make` command will build the plugin.
+`go.mod` is used, so the `go build/test` commands automatically install the needed dependencies
 
+## Building
 
+We have 2 targets in /Makefile:
 
+1. **local-build** It is recommended to use this target "*make local-build*" to make not optimized build for local testing as debugger can't link optimized binary code with its go code to debug it correctly
+2. **gateway-api-plugin-build** It is recommended to use this target "*make gateway-api-plugin-build*" to make optimized build for production when you are sure it is ready for it. We use it to create releases
 
-<!-- ## Running the plugin Locally
 
-It is much easier to run and debug if you run Argo Rollout in your local machine than in the Kubernetes cluster.
+## Running the plugin Locally
 
+1. Create ConfigMap **argo-rollouts-config** in namespace of Argo Rollouts controller. We will run it locally so its namespace will be default
+2. Run **make local-build** to make not optimized local build of plugin. Specify the path to this local build in the ConfigMap that we created before
+```
+file://<path to the local build>
+```
+3. Install needing CRDs for Argo Rollouts and apply its needing manifest. For that you can run
+```bash
+kubectl create namespace argo-rollouts
+kubectl apply -n argo-rollouts -f https://github.com/argoproj/argo-rollouts/releases/latest/download/install.yaml
+```
+After delete in cluster Argo Rollouts controller deployment as we will run controller locally
+4. Run locally Argo Rollouts controller
 ```bash
 cd ~/go/src/github.com/argoproj/argo-rollouts
 go run ./cmd/rollouts-controller/main.go
 ```
+5. If you did all right, Argo Rollouts controller will find your local build of plugin and will run it as RPC server locally. You have ability to debug plugin. Debugger of go has ability to attach to the local process and as we built our plugin without optimizations it also can map binary code with text code of plugin correctly so you can use breakpoints and it will work
 
-When running locally it will connect to whatever kubernetes cluster you have configured in your kubeconfig. You will need to make sure to install the Argo Rollout CRDs into your local cluster, and have the `argo-rollouts` namespace. -->
+## Making releases
 
-## Running Unit Tests
+1. Write in **/RELEASE_NOTES.md** the description of the future release
+2. On needing commit in **main** branch create locally tag
+```bash
+git tag release-v[0-9]+.[0-9]+.[0-9]+
+```
+If you would like to make pre-release run
+```bash
+git tag release-v[0-9]+.[0-9]+.[0-9]+-rc[0-9]+
+```
+3. Push tag to the remote repository
+4. Pushed tag will trigger needing workflow that will create corresponding tag **v[0-9]+.[0-9]+.[0-9]+** or **v[0-9]+.[0-9]+.[0-9]+-rc[0-9]+** and will delete your tag so after pushing tag to the remote repository you need to delete it locally. When workflow will finish its work you can run **git pull** and you will see new tag
 
-<!-- To run unit tests:
+## Running Unit Tests
 
+To run unit tests:
 ```bash
 make test
-``` -->
+```
 
-## Running E2E tests
+<!-- ## Running E2E tests -->
 
 <!-- The end-to-end tests need to run against a kubernetes cluster with the Argo Rollouts controller
 running. The rollout controller can be started with the command:

diff --git a/docs/images/contributing/argo-rollouts-plugin-system-architecture.png b/docs/images/contributing/argo-rollouts-plugin-system-architecture.png
diff --git a/go.mod b/go.mod
@@ -1,75 +1,75 @@
 module github.com/argoproj-labs/rollouts-plugin-trafficrouter-gatewayapi
 
-go 1.20
+go 1.22.0
+
+toolchain go1.22.1
 
 require (
- github.com/argoproj/argo-rollouts v1.5.1
- github.com/hashicorp/go-plugin v1.4.10
+ github.com/argoproj/argo-rollouts v1.6.6
+ github.com/go-playground/validator/v10 v10.19.0
+ github.com/hashicorp/go-plugin v1.6.0
  github.com/sirupsen/logrus v1.9.3
- github.com/stretchr/testify v1.8.4
- k8s.io/client-go v0.28.0
- sigs.k8s.io/gateway-api v0.7.1
+ github.com/stretchr/testify v1.9.0
+ k8s.io/client-go v0.30.0
+ sigs.k8s.io/gateway-api v1.0.0
 )
 
 require (
  github.com/davecgh/go-spew v1.1.1 // indirect
- github.com/evanphx/json-patch v5.6.0+incompatible // indirect
- github.com/fatih/color v1.15.0 // indirect
+ github.com/evanphx/json-patch v5.7.0+incompatible // indirect
+ github.com/fatih/color v1.16.0 // indirect
  github.com/gabriel-vasile/mimetype v1.4.3 // indirect
  github.com/go-playground/locales v0.14.1 // indirect
  github.com/go-playground/universal-translator v0.18.1 // indirect
- github.com/go-playground/validator/v10 v10.18.0 // indirect
  github.com/google/gnostic-models v0.6.8 // indirect
- github.com/google/go-cmp v0.5.9 // indirect
- github.com/google/uuid v1.3.0 // indirect
- github.com/hashicorp/go-hclog v1.5.0 // indirect
+ github.com/google/uuid v1.6.0 // indirect
+ github.com/hashicorp/go-hclog v1.6.3 // indirect
  github.com/hashicorp/yamux v0.1.1 // indirect
  github.com/imdario/mergo v0.3.16 // indirect
  github.com/leodido/go-urn v1.4.0 // indirect
  github.com/mattn/go-colorable v0.1.13 // indirect
- github.com/mattn/go-isatty v0.0.19 // indirect
+ github.com/mattn/go-isatty v0.0.20 // indirect
  github.com/mitchellh/go-testing-interface v1.14.1 // indirect
  github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
  github.com/oklog/run v1.1.0 // indirect
  github.com/pkg/errors v0.9.1 // indirect
  github.com/pmezard/go-difflib v1.0.0 // indirect
  github.com/spf13/pflag v1.0.5 // indirect
- golang.org/x/crypto v0.19.0 // indirect
- golang.org/x/oauth2 v0.11.0 // indirect
- golang.org/x/term v0.17.0 // indirect
- golang.org/x/time v0.3.0 // indirect
- google.golang.org/appengine v1.6.7 // indirect
- google.golang.org/genproto/googleapis/rpc v0.0.0-20230815205213-6bfd019c3878 // indirect
- google.golang.org/grpc v1.57.0 // indirect
- sigs.k8s.io/yaml v1.3.0 // indirect
+ golang.org/x/crypto v0.22.0 // indirect
+ golang.org/x/oauth2 v0.19.0 // indirect
+ golang.org/x/term v0.19.0 // indirect
+ golang.org/x/time v0.5.0 // indirect
+ google.golang.org/genproto/googleapis/rpc v0.0.0-20240415180920-8c6c420018be // indirect
+ google.golang.org/grpc v1.63.2 // indirect
+ sigs.k8s.io/yaml v1.4.0 // indirect
 )
 
 require (
- github.com/emicklei/go-restful/v3 v3.11.0 // indirect
- github.com/go-logr/logr v1.2.4 // indirect
- github.com/go-openapi/jsonpointer v0.20.0 // indirect
- github.com/go-openapi/jsonreference v0.20.2 // indirect
- github.com/go-openapi/swag v0.22.4 // indirect
+ github.com/emicklei/go-restful/v3 v3.12.0 // indirect
+ github.com/go-logr/logr v1.4.1 // indirect
+ github.com/go-openapi/jsonpointer v0.21.0 // indirect
+ github.com/go-openapi/jsonreference v0.21.0 // indirect
+ github.com/go-openapi/swag v0.23.0 // indirect
  github.com/gogo/protobuf v1.3.2 // indirect
- github.com/golang/protobuf v1.5.3 // indirect
+ github.com/golang/protobuf v1.5.4 // indirect
  github.com/google/gofuzz v1.2.0 // indirect
  github.com/josharian/intern v1.0.0 // indirect
  github.com/json-iterator/go v1.1.12 // indirect
  github.com/mailru/easyjson v0.7.7 // indirect
  github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
  github.com/modern-go/reflect2 v1.0.2 // indirect
- golang.org/x/net v0.21.0 // indirect
- golang.org/x/sys v0.17.0 // indirect
+ golang.org/x/net v0.24.0 // indirect
+ golang.org/x/sys v0.19.0 // indirect
  golang.org/x/text v0.14.0 // indirect
- google.golang.org/protobuf v1.31.0 // indirect
+ google.golang.org/protobuf v1.33.0 // indirect
  gopkg.in/inf.v0 v0.9.1 // indirect
  gopkg.in/yaml.v2 v2.4.0 // indirect
  gopkg.in/yaml.v3 v3.0.1 // indirect
- k8s.io/api v0.28.0 // indirect
- k8s.io/apimachinery v0.28.0
- k8s.io/klog/v2 v2.100.1 // indirect
- k8s.io/kube-openapi v0.0.0-20230816210353-14e408962443 // indirect
- k8s.io/utils v0.0.0-20230726121419-3b25d923346b // indirect
+ k8s.io/api v0.30.0
+ k8s.io/apimachinery v0.30.0
+ k8s.io/klog/v2 v2.120.1 // indirect
+ k8s.io/kube-openapi v0.0.0-20240423202451-8948a665c108 // indirect
+ k8s.io/utils v0.0.0-20240423183400-0849a56e8f22 // indirect
  sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
- sigs.k8s.io/structured-merge-diff/v4 v4.3.0 // indirect
+ sigs.k8s.io/structured-merge-diff/v4 v4.4.1 // indirect
 )