docs: updated contributing instructions (projectcontour#5238)

tsaarni · web-flow · commit 44155e167856 · 2023-04-04T15:44:06.000-06:00
* docs: updated contributing instructions
* attempt with kind listening on 127.0.0.1
* set image name based on git hash

Signed-off-by: Tero Saarni &lt;tero.saarni@est.tech&gt;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,7 +2,7 @@
 
 Thanks for taking the time to join our community and start contributing.
 These guidelines will help you get started with the Contour project.
-Please note that we require [DCO sign off](#dco-sign-off).  
+Please note that we require [DCO sign off](#dco-sign-off).
 
 Read this document for additional website specific guildlines: [Site Contribution Guidelines](/SITE_CONTRIBUTION.md).
 Guidelines in this document still apply to website contributions.
@@ -15,11 +15,20 @@ This section describes how to build Contour from source.
 
 ### Prerequisites
 
-1. *Install Go*
+1. Install Docker
 
+    The easiest way to experiment with Contour is to build it in a container and run it locally in [kind](https://kind.sigs.k8s.io/) cluster.
+
+2. Install tools: `git`, `make`, [`kind`](https://kind.sigs.k8s.io/docs/user/quick-start/), `kubectl`, `jq` and `yq`
+
+3. Install Go
+
+    To debug locally and to run unit tests, you will need to install Go.
     Contour generally uses the most recent minor [Go version][1].
     Look in the `Makefile` (search for the `BUILD_BASE_IMAGE` variable) to find the specific version being used.
 
+
+
 ### Fetch the source
 
 Contour uses [`go modules`][2] for dependency management.
@@ -32,9 +41,34 @@ Contour uses [`go modules`][2] for dependency management.
 git clone git@github.com:YOUR-USERNAME/contour.git
 ```
 
-### Building
 
-To build Contour, run:
+### Running your first build
+
+The simplest way to get up and running is to build Contour in a Docker container and to deploy it to a local Kind cluster.
+These commands will launch a Kind cluster and deploy your build of Contour to it.
+
+```shell
+make install-contour-working
+```
+
+or for Contour Gateway Provisioner:
+
+```shell
+make install-provisioner-working
+```
+
+You can access Contour in localhost ports 9080 and 9443.
+
+To remove the Kind cluster and all resources, run:
+
+```shell
+make cleanup-kind
+```
+
+
+### Building locally
+
+To build Contour locally, run:
 
 ```
 make
@@ -65,8 +99,6 @@ Before making a commit, it's always a good idea to check the code for common pro
 make lint
 ```
 
-Note: The lint tasks require the [codespell](https://github.com/codespell-project/codespell) application. Be sure to install version 2.0 or newer before running the lint tasks.
-
 ### Local Development/Testing
 
 It's very helpful to be able to test out changes to Contour locally without building images and pushing into clusters.
@@ -109,9 +141,9 @@ Change `initContainers:` to look like this updating the IP and removing the thre
 
 5. Change your Contour code.
 
-6. Build & start Contour allowing Envoy to connect and get its configuration. 
+6. Build & start Contour allowing Envoy to connect and get its configuration.
 ```shell
-make install && contour serve --kubeconfig=$HOME/.kube/config --xds-address=0.0.0.0 --insecure 
+make install && contour serve --kubeconfig=$HOME/.kube/config --xds-address=0.0.0.0 --insecure
 ```
 
 8. Test using the local kind cluster by deploying resources into that cluster. Many of our examples use `local.projectcontour.io` which is configured to point to `127.0.0.1` which allows requests to route to the local kind cluster for easy testing.
@@ -182,7 +214,7 @@ with a colon as delimiter. For example 'docs:', 'internal/(packagename):', 'desi
 it may have a `release-note/not-required` category. PRs may also include a `release-note/deprecation`
 label alone or in addition to the primary label.
 - PRs *must* include a file named `changelogs/unreleased/PR#-githubID-category.md`, which is a Markdown
-file with a description of the change. Please see `changelogs/unreleased/<category>-sample.md` for 
+file with a description of the change. Please see `changelogs/unreleased/<category>-sample.md` for
 sample changelogs.
 - If main has moved on, you'll need to rebase before we can merge,
 so merging upstream main or rebasing from upstream before opening your
@@ -244,8 +276,8 @@ contour_api_v1 "github.com/projectcontour/contour/apis/projectcontour/v1"
 contour_api_v1alpha1 "github.com/projectcontour/contour/apis/projectcontour/v1alpha1"
 envoy_v3 "github.com/projectcontour/contour/internal/envoy/v3"
 xdscache_v3 "github.com/projectcontour/contour/internal/xdscache/v3"
-```   
- 
+```
+
 ### Pre commit CI
 
 Before a change is submitted it should pass all the pre commit CI jobs.
@@ -283,11 +315,11 @@ This section provides some useful information and guidelines for working with Co
 #### Config/Data Categories
 * **Kubernetes Config**: `HTTPProxy`, `Ingress` or [Gateway API][8] config that Contour watches and converts to Envoy config.
 * **DAG**: The internal Contour representation of L7 proxy concepts. Kubernetes config is first converted to DAG objects before being converted to Envoy config.
-* **Envoy Config**: Configuration that can be provided to Envoy via xDS. This is Contour's final output, generated directly from the DAG. 
+* **Envoy Config**: Configuration that can be provided to Envoy via xDS. This is Contour's final output, generated directly from the DAG.
 
 #### Test Categories
 * **Unit Test**: A Go test for a particular function/package. In some cases, these test more than one package at a time.
-* **Feature Test**: A Go test in `internal/featuretests` that tests the translation of Kubernetes config to Envoy config, using a Contour event handler and xDS server. 
+* **Feature Test**: A Go test in `internal/featuretests` that tests the translation of Kubernetes config to Envoy config, using a Contour event handler and xDS server.
 * **End-To-End (E2E) Test**: A Go test in `test/e2e` that performs a full end-to-end test of Contour running in a cluster. Typically verifies the behavior of HTTP requests given a Kubernetes `HTTPProxy`, `Ingress` or Gateway API config.
 
 ### Summary of Major Test Suites
@@ -370,7 +402,7 @@ By making a contribution to this project, I certify that:
 
 [1]: https://golang.org/dl/
 [2]: https://github.com/golang/go/wiki/Modules
-[3]: https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository 
+[3]: https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository
 [4]: https://golang.org/pkg/testing/
 [5]: https://developercertificate.org/
 [6]: https://github.com/projectcontour/contour/issues/new/choose
diff --git a/hack/codespell.sh b/hack/codespell.sh
@@ -7,6 +7,15 @@ if command -v ${PROGNAME} >/dev/null; then
 	exec ${PROGNAME} "$@"
 fi
 
+if command -v docker >/dev/null; then
+	exec docker run \
+		--rm \
+		--volume $(pwd):/workdir \
+		--workdir=/workdir \
+		--entrypoint=/usr/local/bin/codespell \
+		ghcr.io/codespell-project/actions-codespell/stable:v1.0 "$@"
+fi
+
 cat <<EOF
 Unable to run codespell. Please check installation instructions:
 	https://github.com/codespell-project/codespell#installation
diff --git a/test/scripts/install-contour-working.sh b/test/scripts/install-contour-working.sh
@@ -44,17 +44,10 @@ if ! kind::cluster::exists "$CLUSTERNAME" ; then
     exit 2
 fi
 
-# Wrap sed to deal with GNU and BSD sed flags.
-run::sed() {
-    local -r vers="$(sed --version < /dev/null 2>&1 | grep -q GNU && echo gnu || echo bsd)"
-    case "$vers" in
-        gnu) sed -i "$@" ;;
-        *) sed -i '' "$@" ;;
-    esac
-}
+# Set the image tag to match the current git hash + dirty flag.
+VERSION=$(git describe --exclude="*" --always --dirty)
 
-# Build the current version of Contour.
-VERSION="v$$"
+# Build the image.
 make -C ${REPO} container IMAGE=ghcr.io/projectcontour/contour VERSION=${VERSION}
 
 # Push the Contour build image into the cluster.
@@ -73,17 +66,13 @@ for file in ${REPO}/examples/contour/02-job-certgen.yaml ${REPO}/examples/contou
   # Set image pull policy to IfNotPresent so kubelet will use the
   # images that we loaded onto the node, rather than trying to pull
   # them from the registry.
-  run::sed \
-    "-es|imagePullPolicy: Always|imagePullPolicy: IfNotPresent|" \
-    "$file"
-
   # Set the image tag to $VERSION to unambiguously use the image
   # we built above.
-  run::sed \
+  sed \
+    "-es|imagePullPolicy: Always|imagePullPolicy: IfNotPresent|" \
     "-es|image: ghcr.io/projectcontour/contour:.*$|image: ghcr.io/projectcontour/contour:${VERSION}|" \
-    "$file"
-
-  ${KUBECTL} apply -f "$file"
+    "$file" | \
+  ${KUBECTL} apply -f -
 done
 
 # Wait for Contour and Envoy to report "Ready" status.
diff --git a/test/scripts/install-provisioner-working.sh b/test/scripts/install-provisioner-working.sh
@@ -28,8 +28,8 @@ if ! kind::cluster::exists "$CLUSTERNAME" ; then
     exit 2
 fi
 
-# Set the image tag to match the current Contour version.
-VERSION="v$$"
+# Set the image tag to match the current git hash + dirty flag if repo has modifications.
+VERSION=$(git describe --exclude="*" --always --dirty)
 
 # Build the Contour Provisioner image.
 make -C ${REPO} container IMAGE=ghcr.io/projectcontour/contour VERSION=${VERSION}
diff --git a/test/scripts/kind-expose-port.yaml b/test/scripts/kind-expose-port.yaml
@@ -6,10 +6,10 @@ nodes:
   extraPortMappings:
   - containerPort: 80
     hostPort: 9080
-    listenAddress: "0.0.0.0"
+    listenAddress: "127.0.0.1"
   - containerPort: 443
     hostPort: 9443
-    listenAddress: "0.0.0.0"
+    listenAddress: "127.0.0.1"
   - containerPort: 8002
     hostPort: 8002
-    listenAddress: "0.0.0.0"
+    listenAddress: "127.0.0.1"
