From b1c7b966d2230e0c1b9d8ff1733a4e93fa213526 Mon Sep 17 00:00:00 2001
From: hc-github-team-secure-vault-core
 <82990506+hc-github-team-secure-vault-core@users.noreply.github.com>
Date: Thu, 17 Aug 2023 14:49:23 -0400
Subject: [PATCH] backport of commit 1e491e16d4a25001423434ca950823fbeb9ac1d9
 (#22187)

Co-authored-by: Nick Cabatoff <ncabatoff@hashicorp.com>
---
 Makefile  |   2 +-
 README.md | 117 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 118 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 3c997ad6c..7696ad783 100644
--- a/Makefile
+++ b/Makefile
@@ -159,7 +159,7 @@ ci-lint:
 # dependency.
 prep:
 	@sh -c "'$(CURDIR)/scripts/goversioncheck.sh' '$(GO_VERSION_MIN)'"
-	@$(GO_CMD) generate $$($(GO_CMD) list ./... | grep -v /vendor/)
+	@GOARCH= GOOS= $(GO_CMD) generate $$($(GO_CMD) list ./... | grep -v /vendor/)
 	@if [ -d .git/hooks ]; then cp .hooks/* .git/hooks/; fi
 
 # bootstrap the build by downloading additional tools needed to build
diff --git a/README.md b/README.md
index 7de5fb620..6b640661d 100644
--- a/README.md
+++ b/README.md
@@ -136,6 +136,8 @@ is not, and has never been, a supported way to use the Vault project. We aren't
 likely to fix bugs relating to failure to import `github.com/hashicorp/vault` 
 into your project.
 
+See also the section "Docker-based tests" below.
+
 ### Acceptance Tests
 
 Vault has comprehensive [acceptance tests](https://en.wikipedia.org/wiki/Acceptance_testing)
@@ -169,3 +171,118 @@ things such as access keys. The test itself should error early and tell
 you what to set, so it is not documented here.
 
 For more information on Vault Enterprise features, visit the [Vault Enterprise site](https://www.hashicorp.com/products/vault/?utm_source=github&utm_medium=referral&utm_campaign=github-vault-enterprise).
+
+### Docker-based Tests
+
+We have created an experimental new testing mechanism inspired by NewTestCluster.
+An example of how to use it:
+
+```go
+import (
+  "testing"
+  "github.com/hashicorp/vault/sdk/helper/testcluster/docker"
+)
+
+func Test_Something_With_Docker(t *testing.T) {
+  opts := &docker.DockerClusterOptions{
+    ImageRepo: "hashicorp/vault", // or "hashicorp/vault-enterprise"
+    ImageTag:    "latest",
+  }
+  cluster := docker.NewTestDockerCluster(t, opts)
+  defer cluster.Cleanup()
+  
+  client := cluster.Nodes()[0].APIClient()
+  _, err := client.Logical().Read("sys/storage/raft/configuration")
+  if err != nil {
+    t.Fatal(err)
+  }
+}
+```
+
+Or for Enterprise:
+
+```go
+import (
+  "testing"
+  "github.com/hashicorp/vault/sdk/helper/testcluster/docker"
+)
+
+func Test_Something_With_Docker(t *testing.T) {
+  opts := &docker.DockerClusterOptions{
+    ImageRepo: "hashicorp/vault-enterprise",
+    ImageTag:  "latest",
+	VaultLicense: licenseString, // not a path, the actual license bytes
+  }
+  cluster := docker.NewTestDockerCluster(t, opts)
+  defer cluster.Cleanup()
+}
+```
+
+Here is a more realistic example of how we use it in practice.  DefaultOptions uses 
+`hashicorp/vault`:`latest` as the repo and tag, but it also looks at the environment
+variable VAULT_BINARY. If populated, it will copy the local file referenced by
+VAULT_BINARY into the container. This is useful when testing local changes.
+
+Instead of setting the VaultLicense option, you can set the VAULT_LICENSE_CI environment
+variable, which is better than committing a license to version control.
+
+Optionally you can set COMMIT_SHA, which will be appended to the image name we
+build as a debugging convenience.
+
+```go
+func Test_Custom_Build_With_Docker(t *testing.T) {
+  opts := docker.DefaultOptions(t)
+  cluster := docker.NewTestDockerCluster(t, opts)
+  defer cluster.Cleanup()
+}
+```
+
+There are a variety of helpers in the `github.com/hashicorp/vault/sdk/helper/testcluster`
+package, e.g. these tests below will create a pair of 3-node clusters and link them using
+PR or DR replication respectively, and fail if the replication state doesn't become healthy
+before the passed context expires.
+
+Again, as written, these depend on having a Vault Enterprise binary locally and the env
+var VAULT_BINARY set to point to it, as well as having VAULT_LICENSE_CI set.
+
+```go
+func TestStandardPerfReplication_Docker(t *testing.T) {
+  opts := docker.DefaultOptions(t)
+  r, err := docker.NewReplicationSetDocker(t, opts)
+  if err != nil {
+      t.Fatal(err)
+  }
+  defer r.Cleanup()
+
+  ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+  defer cancel()
+  err = r.StandardPerfReplication(ctx)
+  if err != nil {
+    t.Fatal(err)
+  }
+}
+
+func TestStandardDRReplication_Docker(t *testing.T) {
+  opts := docker.DefaultOptions(t)
+  r, err := docker.NewReplicationSetDocker(t, opts)
+  if err != nil {
+    t.Fatal(err)
+  }
+  defer r.Cleanup()
+
+  ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+  defer cancel()
+  err = r.StandardDRReplication(ctx)
+  if err != nil {
+    t.Fatal(err)
+  }
+}
+```
+
+Finally, here's an example of running an existing OSS docker test with a custom binary:
+
+```bash
+$ GOOS=linux make dev
+$ VAULT_BINARY=$(pwd)/bin/vault go test -run 'TestRaft_Configuration_Docker' ./vault/external_tests/raft/raft_binary
+ok      github.com/hashicorp/vault/vault/external_tests/raft/raft_binary        20.960s
+```