feat: Add info for parameters in zero module definition (#209)

* feat: Add info for parameters in zero module definition

* fix: template syntax

Author: bmonkman

templates/terraform/environments/shared/main.tf

@@ -14,7 +14,7 @@ locals {
   region                 = "<% index .Params `region` %>"
   account_id             = "<% index .Params `accountId` %>"
   random_seed            = "<% index .Params `randomSeed` %>"
-  shared_resource_prefix = "<% index .Params `sharedResourcePrefix` %>"
+  shared_resource_prefix = "<% if ne (index .Params `sharedResourcePrefix`) "none" %><% index .Params `sharedResourcePrefix` %><% end %>"
 }
 
 provider "aws" {

zero-module.yml

@@ -20,6 +20,7 @@ requiredCredentials:
 parameters:
   - field: useExistingAwsProfile
     label: "Use credentials from an existing AWS profile?"
+    info: "You can choose either a currently existing profile if you've already configured your AWS CLI, or manually enter a pair of AWS access keys."
     options:
       "yes": "Yes"
       "no": "No"
@@ -33,6 +34,7 @@ parameters:
       matchField: useExistingAwsProfile
   - field: accessKeyId
     label: AWS AccessKeyId
+    info: "AWS access is controlled by a pair of keys tied to a user account.\nhttps://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html "
     envVarName: "AWS_ACCESS_KEY_ID"
     conditions:
     - action: KeyMatchCondition
@@ -41,106 +43,124 @@ parameters:
   - field: secretAccessKey
     envVarName: "AWS_SECRET_ACCESS_KEY"
     label: AWS SecretAccessKey
+    info: "AWS access is controlled by a pair of keys tied to a user account.\nhttps://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html "
     conditions:
     - action: KeyMatchCondition
       whenValue: "no"
       matchField: useExistingAwsProfile
   - field: githubAccessToken
     label: "Github API Key to setup your repository and optionally CI/CD"
+    info: "This API key will let us set up new repositories to check in your code.\nhttps://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token"
     envVarName: GITHUB_ACCESS_TOKEN
   - field: region
     label: Select AWS Region
+    info: "This is the region your resources will be created in.\nMost regions have all the same features and functionality, but depending on your product you may need to choose a different region for data sovereignty reasons."
     options:
-      "us-west-2": "us-west-2 (Oregon)"
-      "us-east-1": "us-east-1 (N. Virginia)"
-      "us-east-2": "us-east-2 (Ohio)"
+      "us-east-1": "us-east-1 - US East (N. Virginia)"
+      "us-east-2": "us-east-2 - US East (Ohio)"
+      "us-west-2": "us-west-2 - US West (Oregon)"
+      "ca-central-1": "ca-central-1 - Canada (Central)"
+      "eu-west-1": "eu-west-1 - Europe (Ireland)"
+      "ap-southeast-1": "ap-southeast-1 - Asia Pacific (Singapore)"
   - field: productionHostRoot
-    label: Production Root Host Name (e.g. mydomain.com) - this must be the root of the chosen domain, not a subdomain.
+    label: Production Root Host Name (e.g. mydomain.com)
+    info: "This must be the root of the chosen domain, not a subdomain. You will also be prompted for the subdomains to use for your application."
     fieldValidation:
       type: regex
       value: '^([a-z0-9]+(-[a-z0-9]+)*\.{1})+[a-z]{2,}$'
       errorMessage: Invalid root domain name
   - field: productionFrontendSubdomain
     label: Production Frontend Host Name (e.g. app.)
+    info: "The subdomain that will point to the static assets of your frontend hosted in Cloudfront."
     default: app.
     fieldValidation:
       type: regex
       value: '^([a-z0-9]+(-[a-z0-9]+)*\.)$'
       errorMessage: Invalid subdomain (cannot contain special chars & must end with a '.')
   - field: productionBackendSubdomain
     label: Production Backend Host Name (e.g. api.)
+    info: "The subdomain that will point to the API of your backend running in Kubernetes."
     default: api.
     fieldValidation:
       type: regex
       value: '^([a-z0-9]+(-[a-z0-9]+)*\.)$'
       errorMessage: Invalid subdomain (cannot contain special chars & must end with a '.')
   - field: stagingHostRoot
-    label: Staging Root Host Name (e.g. mydomain-staging.com) - this must be the root of the chosen domain, not a subdomain.
+    label: Staging Root Host Name (e.g. mydomain-staging.com)
+    info: "This must be the root of the chosen domain, not a subdomain. You will also be prompted for the subdomains to use for your application.\nIt's recommended that you use different hostnames for staging and production instead of trying to have staging as a subdomain of your production domain."
     fieldValidation:
       type: regex
       value: '^([a-z0-9]+(-[a-z0-9]+)*\.{1})+[a-z]{2,}$'
       errorMessage: Invalid root domain name
   - field: stagingFrontendSubdomain
     label: Staging Frontend Host Name (e.g. app.)
+    info: "The subdomain that will point to the static assets of your frontend hosted in Cloudfront."
     default: app.
     fieldValidation:
       type: regex
       value: '^([a-z0-9]+(-[a-z0-9]+)*\.)$'
       errorMessage: Invalid subdomain (cannot contain special chars & must end with a '.')
   - field: stagingBackendSubdomain
     label: Staging Backend Host Name (e.g. api.)
+    info: "The subdomain that will point to the API of your backend running in Kubernetes."
     default: api.
     fieldValidation:
       type: regex
       value: '^([a-z0-9]+(-[a-z0-9]+)*\.)$'
       errorMessage: Invalid subdomain (cannot contain special chars & must end with a '.')
   - field: CIVendor
-    label: Using either circleCI or github Actions to build / test your repository
+    label: Which CI vendor would you like to use?
+    info: "Build pipelines will be set up which will deploy your code to your infrastructure whenever PRs are merged to the main branch."
     default: "circleci"
     options:
-      "circleci": "CircleCi"
+      "circleci": "CircleCI"
       "github-actions": "Github Actions"
   - field: circleciApiKey
-    label: "Circle CI API Key to setup your CI/CD for repositories"
+    label: "CircleCI API Key"
+    info: "This will let us configure your CircleCI account to automatically enable CI for these newly created projects.\nhttps://circleci.com/docs/2.0/managing-api-tokens/"
     envVarName: CIRCLECI_API_KEY
     conditions:
     - action: KeyMatchCondition
       matchField: CIVendor
       whenValue: "circleci"
   - field: database
-    label: Database engine to use (postgres)
+    label: Database engine to use
+    info: "This will set up a database for you using RDS.\nIt will be accessible only by your application, credentials will be created automatically."
     options:
       "postgres": "PostgreSQL"
       "mysql": "MySQL"
   - field: cacheStore
-    label: "Cache store to use (default: no cache)"
+    label: "Cache store to use"
+    info: "If necessary for your application, this will set up a cache using AWS ElastiCache."
     options:
       "none": "none"
       "redis": "Redis"
       "memcached": "Memcached"
   - field: loggingType
-    label: Application logging to configure. Cloudwatch is cheaper with a more limited feature set. Elasticsearch + Kibana will set up more infrastructure but enable a much richer logging search and visualization experience.
+    label: Which application logging to configure.
+    info: "Cloudwatch is usually cheaper and simpler but with a limited feature set.\nElasticsearch + Kibana will set up more infrastructure but enable a much richer logging search and visualization experience."
     options:
       "cloudwatch": "AWS CloudWatch"
       "kibana": "Kibana"
   - field: metricsType
-    label: Additional application metrics method to configure. Metrics are available through CloudWatch, but choosing prometheus will install Prometheus and Grafana, for a richer metrics experience. No additional infrastructure is required, but a number of prometheus pods will need to exist in the cluster, utilizing some resources.
+    label: Additional application metrics method to configure.
+    info: "Metrics are available through CloudWatch, but choosing prometheus will install Prometheus and Grafana, for a richer metrics experience.\nNo additional infrastructure is required, but a number of prometheus pods will need to exist in the cluster, utilizing some resources."
     options:
       "none": "none"
       "prometheus": "Prometheus"
   - field: notificationServiceEnabled
     label: "Install the Zero Notification Service in your cluster?"
-    info: Provides easy notification capability through email, slack, etc. - https://github.com/commitdev/zero-notification-service
+    info: "Provides easy notification capability through email, slack, SMS, etc.\nhttps://github.com/commitdev/zero-notification-service"
     default: yes
     options:
       "yes": "Yes"
       "no": "No"
   - field: sendgridApiKey
     label: "API key to setup email integration (optional: leave blank to opt-out of Sendgrid setup)"
-    info: Signup at https://signup.sendgrid.com or create an API key at https://app.sendgrid.com/settings/api_keys - Sendgrid is an email delivery service enabling transactional email sending and more.
+    info: "Signup at https://signup.sendgrid.com or create an API key at https://app.sendgrid.com/settings/api_keys\nSendgrid is an email delivery service enabling transactional email sending and more."
   - field: notificationServiceSlackApiKey
-    label: "API key of your Slack bot if you want to use Slack with the Zero Notification Service. Leave blank if not applicable."
-    info: See https://slack.com/intl/en-ca/help/articles/215770388-Create-and-regenerate-API-tokens
+    label: "API key of your Slack bot if you want to use Slack with the Zero Notification Service."
+    info: "Leave blank if you don't intend to use the Slack functionality.\nSee https://slack.com/intl/en-ca/help/articles/215770388-Create-and-regenerate-API-tokens"
     conditions:
     - action: KeyMatchCondition
       whenValue: "yes"
@@ -152,17 +172,19 @@ parameters:
     label: Random seed that will be shared between projects to come up with deterministic resource names
     execute: uuidgen | head -c 8
   - field: fileUploads
-    label: Enable file uploads using S3 and Cloudfront signed URLs? (Will require manual creation of a Cloudfront keypair in AWS)
+    label: Enable file uploads using S3 and Cloudfront signed URLs?
+    info: "This will allow secure file uploads and downloads through your application.\nIt will require manual creation of a Cloudfront keypair in AWS. See https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html"
     default: yes
     options:
       "yes": "Yes"
       "no": "No"
   - field: userAuth
-    label: Enable user management using Kratos and authentication using the Oathkeeper access proxy?
+    label: Enable user management and auth access proxy?
+    info: "This will enable infrastructure and application code that uses Kratos for user management and the Oathkeeper access proxy.\nhttps://ory.sh"
     default: yes
     options:
       "yes": "Yes"
       "no": "No"
   - field: sharedResourcePrefix
     label: "Mostly for development - Allow shared resources to have a unique prefix. This is only necessary if many zero projects will be run in the same AWS account."
-    value: ""
+    value: "none"