Add 'how to run' instructions to each Enos scenario (#29299)

* Add 'how to run' instructions for each scenario

enos/enos-dev-scenario-pr-replication.hcl

@@ -6,8 +6,8 @@ scenario "dev_pr_replication" {
     This scenario spins up a two Vault clusters with either an external Consul cluster or
     integrated Raft for storage. The secondary cluster is configured with performance replication
     from the primary cluster. None of our test verification is included in this scenario in order
-    to improve end-to-end speed. If you wish to perform such verification you'll need to a non-dev
+    to improve end-to-end speed. If you wish to perform such verification you'll need to use a
-    scenario.
+    non-dev scenario.
 
     The scenario supports finding and installing any released 'linux/amd64' or 'linux/arm64' Vault
     artifact as long as its version is >= 1.8. You can also use the 'artifact:local' variant to
@@ -15,12 +15,12 @@ scenario "dev_pr_replication" {
 
     In order to execute this scenario you'll need to install the enos CLI:
       - $ brew tap hashicorp/tap && brew update && brew install hashicorp/tap/enos
-
+    
     You'll also need access to an AWS account via Doormat, follow the guide here:
-      https://eng-handbook.hashicorp.services/internal-tools/enos/common-setup-steps/#authenticate-with-doormat
+      https://eng-handbook.hashicorp.services/internal-tools/enos/getting-started/#authenticate-to-aws-with-doormat
 
     Follow this guide to get an SSH keypair set up in the AWS account:
-      https://eng-handbook.hashicorp.services/internal-tools/enos/common-setup-steps/#set-your-aws-key-pair-name-and-private-key
+      https://eng-handbook.hashicorp.services/internal-tools/enos/getting-started/#set-your-aws-key-pair-name-and-private-key
 
     Please note that this scenario requires several inputs variables to be set in order to function
     properly. While not all variants will require all variables, it's suggested that you look over
@@ -162,15 +162,18 @@ scenario "dev_pr_replication" {
         artifactory_host:
           The artifactory host to search. It's very unlikely that you'll want to change this. The
           default value is the HashiCorp Artifactory instance.
-        artifactory_repo
+        artifactory_repo:
           The artifactory host to search. It's very unlikely that you'll want to change this. The
           default value is where CRT will publish packages.
-        artifactory_username
+        artifactory_username:
           The artifactory username associated with your token. You'll need this if you wish to use
           deb or rpm artifacts! You can request access via Okta.
-        artifactory_token
+        artifactory_token:
           The artifactory token associated with your username. You'll need this if you wish to use
           deb or rpm artifacts! You can create a token by logging into Artifactory via Okta.
+        dev_build_local_ui:
+          If you are not testing any changes in the UI, set to false. This will save time by not
+          building the entire UI. If you need to test the UI, set to true.
         vault_product_version:
           When using the artifact:rpm or artifact:deb variants we'll use this variable to determine
           which version of the Vault pacakge we should fetch from Artifactory.
@@ -207,7 +210,7 @@ scenario "dev_pr_replication" {
   }
 
   step "ec2_info" {
-    description = "This discovers usefull metadata in Ec2 like AWS AMI ID's that we use in later modules."
+    description = "This discovers usefull metadata in Ec2 like AWS AMI IDs that we use in later modules."
     module      = module.ec2_info
   }
 

enos/enos-dev-scenario-single-cluster.hcl

@@ -15,9 +15,11 @@ scenario "dev_single_cluster" {
     In order to execute this scenario you'll need to install the enos CLI:
       brew tap hashicorp/tap && brew update && brew install hashicorp/tap/enos
 
-    You'll also need access to an AWS account with an SSH keypair.
+    You'll also need access to an AWS account via Doormat, follow the guide here:
-    Perform the steps here to get AWS access with Doormat https://eng-handbook.hashicorp.services/internal-tools/enos/common-setup-steps/#authenticate-with-doormat
+      https://eng-handbook.hashicorp.services/internal-tools/enos/getting-started/#authenticate-to-aws-with-doormat
-    Perform the steps here to get an AWS keypair set up: https://eng-handbook.hashicorp.services/internal-tools/enos/common-setup-steps/#set-your-aws-key-pair-name-and-private-key
+
+    Follow this guide to get an SSH keypair set up in the AWS account:
+      https://eng-handbook.hashicorp.services/internal-tools/enos/getting-started/#set-your-aws-key-pair-name-and-private-key
 
     Please note that this scenario requires several inputs variables to be set in order to function
     properly. While not all variants will require all variables, it's suggested that you look over
@@ -44,6 +46,9 @@ scenario "dev_single_cluster" {
     dev_consul_version        = "1.18.1"
     vault_license_path        = "./support/vault.hclic"
     vault_product_version     = "1.16.2"
+    Alternatively, you can set them in your environment:
+    export ENOS_VAR_aws_region="us-west-2"
+    export ENOS_VAR_vault_license_path="./support/vault.hclic"
 
     Alternatively, you can set them in your environment:
     export ENOS_VAR_aws_region="us-west-2"
@@ -154,15 +159,18 @@ scenario "dev_single_cluster" {
         artifactory_host:
           The artifactory host to search. It's very unlikely that you'll want to change this. The
           default value is the HashiCorp Artifactory instance.
-        artifactory_repo
+        artifactory_repo:
           The artifactory host to search. It's very unlikely that you'll want to change this. The
           default value is where CRT will publish packages.
-        artifactory_username
+        artifactory_username:
           The artifactory username associated with your token. You'll need this if you wish to use
           deb or rpm artifacts! You can request access via Okta.
-        artifactory_token
+        artifactory_token:
           The artifactory token associated with your username. You'll need this if you wish to use
           deb or rpm artifacts! You can create a token by logging into Artifactory via Okta.
+        dev_build_local_ui:
+          If you are not testing any changes in the UI, set to false. This will save time by not
+          building the entire UI. If you need to test the UI, set to true.
         vault_product_version:
           When using the artifact:rpm or artifact:deb variants we'll use this variable to determine
           which version of the Vault pacakge we should fetch from Artifactory.

enos/enos-scenario-agent.hcl

@@ -6,16 +6,37 @@ scenario "agent" {
     The agent scenario verifies Vault when running in Agent mode. The build can be a local branch,
     any CRT built Vault artifact saved to the local machine, or any CRT built Vault artifact in the
     stable channel in Artifactory.
-
+    
     The scenario creates a new Vault Cluster using the candidate build and then runs the same Vault
     build in Agent mode and verifies behavior against the Vault cluster. The scenario also performs
     standard baseline verification that is not specific to the Agent mode deployment.
 
-    If you want to use the 'distro:leap' variant you must first accept SUSE's terms for the AWS
+    # How to run this scenario
-    account. To verify that your account has agreed, sign-in to your AWS through Doormat,
+
-    and visit the following links to verify your subscription or subscribe:
+    For general instructions on running a scenario, refer to the Enos docs: https://eng-handbook.hashicorp.services/internal-tools/enos/running-a-scenario/
-      arm64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=a516e959-df54-4035-bb1a-63599b7a6df9
+    For troubleshooting tips and common errors, see https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/.
-      amd64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=5535c495-72d4-4355-b169-54ffa874f849
+
+    Variables required for all scenario variants:
+      - aws_ssh_private_key_path (more info about AWS SSH keypairs: https://eng-handbook.hashicorp.services/internal-tools/enos/getting-started/#set-your-aws-key-pair-name-and-private-key)
+      - aws_ssh_keypair_name
+      - vault_build_date*
+      - vault_product_version
+      - vault_revision*
+    
+    * If you don't already know what build date and revision you should be using, see
+    https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/#execution-error-expected-vs-got-for-vault-versioneditionrevisionbuild-date.
+  
+    Variables required for some scenario variants:
+      - artifactory_username (if using `artifact_source:artifactory` in your filter)
+      - artifactory_token (if using `artifact_source:artifactory` in your filter)
+      - aws_region (if different from the default value in enos-variables.hcl)
+      - consul_license_path (if using an ENT edition of Consul)
+      - distro_version_<distro> (if different from the default version for your target
+      distro. See supported distros and default versions in the distro_version_<distro>
+      definitions in enos-variables.hcl)
+      - vault_artifact_path (the path to where you have a Vault artifact already downloaded,
+      if using `artifact_source:crt` in your filter)
+      - vault_license_path (if using an ENT edition of Vault)
   EOF
 
   matrix {

enos/enos-scenario-autopilot.hcl

@@ -13,11 +13,34 @@ scenario "autopilot" {
     The scenario also performs standard baseline verification that is not specific to the autopilot
     upgrade.
 
-    If you want to use the 'distro:leap' variant you must first accept SUSE's terms for the AWS
+    # How to run this scenario
-    account. To verify that your account has agreed, sign-in to your AWS through Doormat,
+
-    and visit the following links to verify your subscription or subscribe:
+    For general instructions on running a scenario, refer to the Enos docs: https://eng-handbook.hashicorp.services/internal-tools/enos/running-a-scenario/
-      arm64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=a516e959-df54-4035-bb1a-63599b7a6df9
+    For troubleshooting tips and common errors, see https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/.
-      amd64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=5535c495-72d4-4355-b169-54ffa874f849
+
+    Variables required for all scenario variants:
+      - aws_ssh_private_key_path (more info about AWS SSH keypairs: https://eng-handbook.hashicorp.services/internal-tools/enos/getting-started/#set-your-aws-key-pair-name-and-private-key)
+      - aws_ssh_keypair_name
+      - vault_build_date*
+      - vault_product_version
+      - vault_revision*
+    
+    * If you don't already know what build date and revision you should be using, see
+    https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/#execution-error-expected-vs-got-for-vault-versioneditionrevisionbuild-date.
+  
+    Variables required for some scenario variants:
+      - artifactory_username (if using `artifact_source:artifactory` in your filter)
+      - artifactory_token (if using `artifact_source:artifactory` in your filter)
+      - aws_region (if different from the default value defined in enos-variables.hcl)
+      - consul_license_path (if using an ENT edition of Consul)
+      - distro_version_<distro> (if different from the default version for your target
+      distro. See supported distros and default versions in the distro_version_<distro>
+      definitions in enos-variables.hcl)
+      - vault_artifact_path (the path to where you have a Vault artifact already downloaded,
+      if using `artifact_source:crt` in your filter)
+      - vault_license_path (if using an ENT edition of Vault)
+      - vault_upgrade_initial_version (if the version you want to start with differs
+      from the default value defined in enos-variables.hcl)
   EOF
 
   matrix {

enos/enos-scenario-dr-replication.hcl

@@ -16,11 +16,32 @@ scenario "dr_replication" {
     Finally, we verify that the secondary cluster is unsealed after enabling replication and verify the
     disaster recovery replication status between the primary and secondary clusters.
 
-    If you want to use the 'distro:leap' variant you must first accept SUSE's terms for the AWS
+    # How to run this scenario
-    account. To verify that your account has agreed, sign-in to your AWS through Doormat,
+
-    and visit the following links to verify your subscription or subscribe:
+    For general instructions on running a scenario, refer to the Enos docs: https://eng-handbook.hashicorp.services/internal-tools/enos/running-a-scenario/
-      arm64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=a516e959-df54-4035-bb1a-63599b7a6df9
+    For troubleshooting tips and common errors, see https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/.
-      amd64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=5535c495-72d4-4355-b169-54ffa874f849
+
+    Variables required for all scenario variants:
+      - aws_ssh_private_key_path (more info about AWS SSH keypairs: https://eng-handbook.hashicorp.services/internal-tools/enos/getting-started/#set-your-aws-key-pair-name-and-private-key)
+      - aws_ssh_keypair_name
+      - vault_build_date*
+      - vault_product_version
+      - vault_revision*
+    
+    * If you don't already know what build date and revision you should be using, see
+    https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/#execution-error-expected-vs-got-for-vault-versioneditionrevisionbuild-date.
+  
+    Variables required for some scenario variants:
+      - artifactory_username (if using `artifact_source:artifactory` in your filter)
+      - artifactory_token (if using `artifact_source:artifactory` in your filter)
+      - aws_region (if different from the default value in enos-variables.hcl)
+      - consul_license_path (if using an ENT edition of Consul)
+      - distro_version_<distro> (if different from the default version for your target
+      distro. See supported distros and default versions in the distro_version_<distro>
+      definitions in enos-variables.hcl)
+      - vault_artifact_path (the path to where you have a Vault artifact already downloaded,
+      if using `artifact_source:crt` in your filter)
+      - vault_license_path (if using an ENT edition of Vault)
   EOF
 
   matrix {

enos/enos-scenario-pr-replication.hcl

@@ -9,18 +9,39 @@ scenario "pr_replication" {
     the stable channel in Artifactory.
 
     The scenario deploys two Vault Enterprise clusters and establishes performance replication
-    between the primary cluster and the performance replication secondary cluster. Next, we simulate
+    between the primary cluster and the performance replication secondary cluster. Next, it simulates
-    a catastrophic failure event whereby the primary leader and a primary follower as ungracefully
+    a catastrophic failure event whereby the primary leader and a primary follower are ungracefully
     removed from the cluster while running. This forces a leader election in the primary cluster
     and requires the secondary cluster to recover replication and establish replication to the new
     primary leader. The scenario also performs standard baseline verification that is not specific
     to performance replication.
 
-    If you want to use the 'distro:leap' variant you must first accept SUSE's terms for the AWS
+    # How to run this scenario
-    account. To verify that your account has agreed, sign-in to your AWS through Doormat,
+
-    and visit the following links to verify your subscription or subscribe:
+    For general instructions on running a scenario, refer to the Enos docs: https://eng-handbook.hashicorp.services/internal-tools/enos/running-a-scenario/
-      arm64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=a516e959-df54-4035-bb1a-63599b7a6df9
+    For troubleshooting tips and common errors, see https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/.
-      amd64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=5535c495-72d4-4355-b169-54ffa874f849
+
+    Variables required for all scenario variants:
+      - aws_ssh_private_key_path (more info about AWS SSH keypairs: https://eng-handbook.hashicorp.services/internal-tools/enos/getting-started/#set-your-aws-key-pair-name-and-private-key)
+      - aws_ssh_keypair_name
+      - vault_build_date*
+      - vault_product_version
+      - vault_revision*
+    
+    * If you don't already know what build date and revision you should be using, see
+    https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/#execution-error-expected-vs-got-for-vault-versioneditionrevisionbuild-date.
+  
+    Variables required for some scenario variants:
+      - artifactory_username (if using `artifact_source:artifactory` in your filter)
+      - artifactory_token (if using `artifact_source:artifactory` in your filter)
+      - aws_region (if different from the default value in enos-variables.hcl)
+      - consul_license_path (if using an ENT edition of Consul)
+      - distro_version_<distro> (if different from the default version for your target
+      distro. See supported distros and default versions in the distro_version_<distro>
+      definitions in enos-variables.hcl)
+      - vault_artifact_path (the path to where you have a Vault artifact already downloaded,
+      if using `artifact_source:crt` in your filter)
+      - vault_license_path (if using an ENT edition of Vault)
   EOF
 
   matrix {

enos/enos-scenario-proxy.hcl

@@ -3,19 +3,40 @@
 
 scenario "proxy" {
   description = <<-EOF
-  The agent scenario verifies Vault when running in Proxy mode. The build can be a local branch,
+  The proxy scenario verifies Vault when running in Proxy mode. The build can be a local branch,
     any CRT built Vault artifact saved to the local machine, or any CRT built Vault artifact in the
     stable channel in Artifactory.
 
-    The scenario creates a new Vault Cluster using the candidate build and then runs the same Vault
+  The scenario creates a new Vault Cluster using the candidate build and then runs the same Vault
-    build in Proxy mode and verifies behavior against the Vault cluster. The scenario also performs
+  build in Proxy mode and verifies behavior against the Vault cluster. The scenario also performs
-    standard baseline verification that is not specific to the Proxy mode deployment.
+  standard baseline verification that is not specific to the Proxy mode deployment.
 
-    If you want to use the 'distro:leap' variant you must first accept SUSE's terms for the AWS
+  # How to run this scenario
-    account. To verify that your account has agreed, sign-in to your AWS through Doormat,
+
-    and visit the following links to verify your subscription or subscribe:
+  For general instructions on running a scenario, refer to the Enos docs: https://eng-handbook.hashicorp.services/internal-tools/enos/running-a-scenario/
-      arm64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=a516e959-df54-4035-bb1a-63599b7a6df9
+  For troubleshooting tips and common errors, see https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/.
-      amd64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=5535c495-72d4-4355-b169-54ffa874f849
+
+  Variables required for all scenario variants:
+    - aws_ssh_private_key_path (more info about AWS SSH keypairs: https://eng-handbook.hashicorp.services/internal-tools/enos/getting-started/#set-your-aws-key-pair-name-and-private-key)
+    - aws_ssh_keypair_name
+    - vault_build_date*
+    - vault_product_version
+    - vault_revision*
+  
+  * If you don't already know what build date and revision you should be using, see
+  https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/#execution-error-expected-vs-got-for-vault-versioneditionrevisionbuild-date.
+
+  Variables required for some scenario variants:
+    - artifactory_username (if using `artifact_source:artifactory` in your filter)
+    - artifactory_token (if using `artifact_source:artifactory` in your filter)
+    - aws_region (if different from the default value in enos-variables.hcl)
+    - consul_license_path (if using an ENT edition of Consul)
+    - distro_version_<distro> (if different from the default version for your target
+    distro. See supported distros and default versions in the distro_version_<distro>
+    definitions in enos-variables.hcl)
+    - vault_artifact_path (the path to where you have a Vault artifact already downloaded,
+    if using `artifact_source:crt` in your filter)
+    - vault_license_path (if using an ENT edition of Vault)
   EOF
 
   matrix {

enos/enos-scenario-seal-ha.hcl

@@ -9,16 +9,37 @@ scenario "seal_ha" {
 
     The scenario deploys a Vault Enterprise cluster with the candidate build and enables a single
     primary seal, mounts various engines and writes data, then establishes seal HA with a secondary
-    seal, the removes the primary and verifies data integrity and seal data migration. It also
+    seal, then removes the primary and verifies data integrity and seal data migration. It also
     verifies that the cluster is able to recover from a forced leader election after the initial
     seal rewrap. The scenario also performs standard baseline verification that is not specific to
     seal_ha.
 
-    If you want to use the 'distro:leap' variant you must first accept SUSE's terms for the AWS
+    # How to run this scenario
-    account. To verify that your account has agreed, sign-in to your AWS through Doormat,
+
-    and visit the following links to verify your subscription or subscribe:
+    For general instructions on running a scenario, refer to the Enos docs: https://eng-handbook.hashicorp.services/internal-tools/enos/running-a-scenario/
-      arm64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=a516e959-df54-4035-bb1a-63599b7a6df9
+    For troubleshooting tips and common errors, see https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/.
-      amd64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=5535c495-72d4-4355-b169-54ffa874f849
+
+    Variables required for all scenario variants:
+      - aws_ssh_private_key_path (more info about AWS SSH keypairs: https://eng-handbook.hashicorp.services/internal-tools/enos/getting-started/#set-your-aws-key-pair-name-and-private-key)
+      - aws_ssh_keypair_name
+      - vault_build_date*
+      - vault_product_version
+      - vault_revision*
+    
+    * If you don't already know what build date and revision you should be using, see
+    https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/#execution-error-expected-vs-got-for-vault-versioneditionrevisionbuild-date.
+  
+    Variables required for some scenario variants:
+      - artifactory_username (if using `artifact_source:artifactory` in your filter)
+      - artifactory_token (if using `artifact_source:artifactory` in your filter)
+      - aws_region (if different from the default value in enos-variables.hcl)
+      - consul_license_path (if using an ENT edition of Consul)
+      - distro_version_<distro> (if different from the default version for your target
+      distro. See supported distros and default versions in the distro_version_<distro>
+      definitions in enos-variables.hcl)
+      - vault_artifact_path (the path to where you have a Vault artifact already downloaded,
+      if using `artifact_source:crt` in your filter)
+      - vault_license_path (if using an ENT edition of Vault)
   EOF
 
   matrix {

enos/enos-scenario-smoke.hcl

@@ -3,18 +3,39 @@
 
 scenario "smoke" {
   description = <<-EOF
-    The smoke scenario verifies a Vault cluster in a fresh installation. The build can be a local
+    The smoke scenario verifies a Vault cluster in a fresh installation. The build can be a local branch,
-    branch, any CRT built Vault artifact saved to the local machine, or any CRT built Vault artifact
+    any CRT built Vault artifact saved to the local machine, or any CRT built Vault artifact in the
-    in the stable channel in Artifactory.
+    stable channel in Artifactory.
 
-    The scenario deploys a Vault cluster with the candidate build performs an extended set of
+    The scenario deploys a Vault cluster with the candidate build and performs an extended
-    baseline verification.
+    set of baseline verification.
 
-    If you want to use the 'distro:leap' variant you must first accept SUSE's terms for the AWS
+    # How to run this scenario
-    account. To verify that your account has agreed, sign-in to your AWS through Doormat,
+
-    and visit the following links to verify your subscription or subscribe:
+    For general instructions on running a scenario, refer to the Enos docs: https://eng-handbook.hashicorp.services/internal-tools/enos/running-a-scenario/
-      arm64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=a516e959-df54-4035-bb1a-63599b7a6df9
+    For troubleshooting tips and common errors, see https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/.
-      amd64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=5535c495-72d4-4355-b169-54ffa874f849
+
+    Variables required for all scenario variants:
+      - aws_ssh_private_key_path (more info about AWS SSH keypairs: https://eng-handbook.hashicorp.services/internal-tools/enos/getting-started/#set-your-aws-key-pair-name-and-private-key)
+      - aws_ssh_keypair_name
+      - vault_build_date*
+      - vault_product_version
+      - vault_revision*
+    
+    * If you don't already know what build date and revision you should be using, see
+    https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/#execution-error-expected-vs-got-for-vault-versioneditionrevisionbuild-date.
+  
+    Variables required for some scenario variants:
+      - artifactory_username (if using `artifact_source:artifactory` in your filter)
+      - artifactory_token (if using `artifact_source:artifactory` in your filter)
+      - aws_region (if different from the default value in enos-variables.hcl)
+      - consul_license_path (if using an ENT edition of Consul)
+      - distro_version_<distro> (if different from the default version for your target
+      distro. See supported distros and default versions in the distro_version_<distro>
+      definitions in enos-variables.hcl)
+      - vault_artifact_path (the path to where you have a Vault artifact already downloaded,
+      if using `artifact_source:crt` in your filter)
+      - vault_license_path (if using an ENT edition of Vault)
   EOF
 
   matrix {

enos/enos-scenario-ui.hcl

@@ -3,14 +3,23 @@
 
 scenario "ui" {
   description = <<-EOF
-    The UI scenario is designed to create a new cluster and run the existing Ember test suite
+    The UI scenario creates a new cluster and runs the existing Ember test suite
-    against a live Vault cluster instead of a binary in dev mode.
+    against a live Vault cluster instead of a binary in dev mode. It builds Vault
+    from the local branch.
 
-    The UI scenario verifies the Vault ember test suite against a Vault cluster. The build can be a
+    # How to run this scenario
-    local branch, any CRT built Vault artifact saved to the local machine, or any CRT built Vault
-    artifact in the stable channel in Artifactory.
 
-    The scenario deploys a Vault cluster with the candidate build and executes the ember test suite.
+    For general instructions on running a scenario, refer to the Enos docs: https://eng-handbook.hashicorp.services/internal-tools/enos/running-a-scenario/
+    For troubleshooting tips and common errors, see https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/.
+
+    Variables required for all scenario variants:
+      - aws_ssh_private_key_path (more info about AWS SSH keypairs: https://eng-handbook.hashicorp.services/internal-tools/enos/getting-started/#set-your-aws-key-pair-name-and-private-key)
+      - aws_ssh_keypair_name
+      - vault_product_version
+
+    Variables required for some scenario variants:
+      - consul_license_path (if using an ENT edition of Consul)
+      - vault_license_path (if using an ENT edition of Vault)
   EOF
   matrix {
     backend        = global.backends

enos/enos-scenario-upgrade.hcl

@@ -5,18 +5,40 @@ scenario "upgrade" {
   description = <<-EOF
     The upgrade scenario verifies in-place upgrades between previously released versions of Vault
     against another candidate build. The build can be a local branch, any CRT built Vault artifact
-    saved to the local machine, or any CRT built Vault artifact in the stable channel in
+    saved to the local machine, or any CRT built Vault artifact in the stable channel in Artifactory.
-    Artifactory.
 
-    The scenario will first create a new Vault Cluster with a previously released version of Vault,
+    The scenario creates a new Vault cluster with a previously released version of Vault. It then
-    mount engines and create data, then perform an in-place upgrade with any candidate built and
+    mounts engines, creates data, and performs an in-place upgrade with any candidate built. Finally,
-    perform quality verification.
+    it performs quality verification.
 
-    If you want to use the 'distro:leap' variant you must first accept SUSE's terms for the AWS
+    # How to run this scenario
-    account. To verify that your account has agreed, sign-in to your AWS through Doormat,
+
-    and visit the following links to verify your subscription or subscribe:
+    For general instructions on running a scenario, refer to the Enos docs: https://eng-handbook.hashicorp.services/internal-tools/enos/running-a-scenario/
-      arm64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=a516e959-df54-4035-bb1a-63599b7a6df9
+    For troubleshooting tips and common errors, see https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/.
-      amd64 AMI: https://aws.amazon.com/marketplace/server/procurement?productId=5535c495-72d4-4355-b169-54ffa874f849
+
+    Variables required for all scenario variants:
+      - aws_ssh_private_key_path (more info about AWS SSH keypairs: https://eng-handbook.hashicorp.services/internal-tools/enos/getting-started/#set-your-aws-key-pair-name-and-private-key)
+      - aws_ssh_keypair_name
+      - vault_build_date*
+      - vault_product_version
+      - vault_revision*
+    
+    * If you don't already know what build date and revision you should be using, see
+    https://eng-handbook.hashicorp.services/internal-tools/enos/troubleshooting/#execution-error-expected-vs-got-for-vault-versioneditionrevisionbuild-date.
+  
+    Variables required for some scenario variants:
+      - artifactory_username (if using `artifact_source:artifactory` in your filter)
+      - artifactory_token (if using `artifact_source:artifactory` in your filter)
+      - aws_region (if different from the default value in enos-variables.hcl)
+      - consul_license_path (if using an ENT edition of Consul)
+      - distro_version_<distro> (if different from the default version for your target
+      distro. See supported distros and default versions in the distro_version_<distro>
+      definitions in enos-variables.hcl)
+      - vault_artifact_path (the path to where you have a Vault artifact already downloaded,
+      if using `artifact_source:crt` in your filter)
+      - vault_license_path (if using an ENT edition of Vault)
+      - vault_upgrade_initial_version (if the version you want to start with differs
+      from the default value defined in enos-variables.hcl)
   EOF
 
   matrix {