Separate specific from common configuration
Introduce a Configuration markdown file to document the configuration
that is invariant to the recipes. Recipe-specific documentation is left
to the relevant README.md file.
Bug: Issue 13059
Change-Id: If4eb95a66a0d21f6c919181d9e6dfcad39d7a42f
diff --git a/Configuration.md b/Configuration.md
new file mode 100644
index 0000000..e104f6d
--- /dev/null
+++ b/Configuration.md
@@ -0,0 +1,65 @@
+# Configuration
+
+Each recipe provides a `setup.env.template` file which is a template for configuring the Gerrit stacks.
+Copy that into a `setup.env` and set the correct values for the provided environment variables.
+
+```bash
+cp setup.env.template setup.env
+```
+Here below a list of variables that are common and need to be specified regardless the recipe you want to
+deploy. Please refer to the individual recipes to understand what additional variables need to be set.
+
+## Common parameters
+
+#### Environment
+
+Configuration values affecting deployment environment and cluster properties
+
+* `DOCKER_REGISTRY_URI`: Mandatory. URI of the Docker registry. See the
+ [prerequisites](Prerequisites.md) section for more details.
+* `SSL_CERTIFICATE_ARN`: Mandatory. ARN of the wildcard SSL Certificate, covering both master nodes.
+* `CLUSTER_STACK_NAME`: Optional. Name of the cluster stack. `gerrit-cluster` by default.
+* `DNS_ROUTING_STACK_NAME`: Optional. Name of the DNS routing stack. `gerrit-dns-routing` by default.
+* `HOSTED_ZONE_NAME`: Optional. Name of the hosted zone. `mycompany.com` by default.
+* `GERRIT_KEY_PREFIX` : Optional. Secrets prefix used during the [Import into AWS Secret Manager](#import-into-aws-secret-manager).
+ `gerrit_secret` by default.
+
+#### SPECS
+
+Configuration values to spec up Gerrit containers.
+
+* `GERRIT_RAM`: RAM allocated (MiB) to the Gerrit container. `70000` by default.
+* `GERRIT_CPU`: vCPU units allocated to the Gerrit container. `10240` by default.
+* `GERRIT_HEAP_LIMIT`: Maximum heap size of the Java process running Gerrit, in bytes.
+ See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#container.heapLimit)
+ `35g` by default.
+* `JGIT_CACHE_SIZE`: Maximum number of bytes to load and cache in memory from pack files.
+ See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#core.packedGitLimit)
+ for more details. `12g` by default.
+
+#### LDAP
+
+Configuration values related to LDAP integration.
+See more details [here](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap)
+
+* `LDAP_SERVER`: Mandatory. URL of the organization’s LDAP server to query for user information and group membership from
+ See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.server)
+* `LDAP_USERNAME`: Mandatory. Username to bind to the LDAP server with
+ See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.username)
+* `LDAP_ACCOUNT_BASE`: Mandatory. Root of the tree containing all user accounts
+ See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.accountBase)
+* `LDAP_GROUP_BASE`: Mandatory. Root of the tree containing all group objects
+ See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.groupBase)
+
+#### SMTP
+
+Configuration values related to SMTP integration.
+See more details [here](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail)
+
+* `SMTP_SERVER`: Mandatory. Hostname (or IP address) of a SMTP server that will relay messages generated by Gerrit to end users
+ See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail.smtpServer)
+* `SMTP_USER`: Mandatory. User name to authenticate with
+ See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail.smtpUser)
+* `SMTP_DOMAIN`: Mandatory. Domain to be used in the "From" field of any generated email messages
+ See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail.from)
+
diff --git a/dual-master/README.md b/dual-master/README.md
index 82b475d..d792651 100644
--- a/dual-master/README.md
+++ b/dual-master/README.md
@@ -68,71 +68,25 @@
### 1 - Configuration
-Each recipe provides a `setup.env.template` file which is a template for configuring the Gerrit stacks.
-Copy that into a `setup.env` and set the correct values for the provided environment variables.
-
-```bash
-cp setup.env.template setup.env
-```
-
-This is the list of available parameters:
+Please refer to the [configuration docs](../Configuration.md) to understand how to set up the
+configuration and what common configuration values are needed.
+On top of that, you might set the additional parameters, specific for this recipe.
#### Environment
Configuration values affecting deployment environment and cluster properties
-* `DOCKER_REGISTRY_URI`: Mandatory. URI of the Docker registry. See the
- [prerequisites](#prerequisites) section for more details.
-* `SSL_CERTIFICATE_ARN`: Mandatory. ARN of the wildcard SSL Certificate, covering both master nodes.
-* `CLUSTER_STACK_NAME`: Optional. Name of the cluster stack. `gerrit-cluster` by default.
* `SERVICE_MASTER1_STACK_NAME`: Optional. Name of the master 1 service stack. `gerrit-service-master-1` by default.
* `SERVICE_MASTER2_STACK_NAME`: Optional. Name of the master 2 service stack. `gerrit-service-master-2` by default.
-* `DNS_ROUTING_STACK_NAME`: Optional. Name of the DNS routing stack. `gerrit-dns-routing` by default.
-* `HOSTED_ZONE_NAME`: Optional. Name of the hosted zone. `mycompany.com` by default.
* `MASTER1_SUBDOMAIN`: Optional. Name of the master 1 sub domain. `gerrit-master-1-demo` by default.
* `MASTER2_SUBDOMAIN`: Optional. Name of the master 2 sub domain. `gerrit-master-2-demo` by default.
-* `CLUSTER_DESIRED_CAPACITY`: Optional. Number of EC2 instances composing the cluster. `1` by default.
-* `GERRIT_KEY_PREFIX` : Optional. Secrets prefix used during the [Import into AWS Secret Manager](#import-into-aws-secret-manager).
- `gerrit_secret` by default.
-
-#### SPECS
-
-Configuration values to spec up Gerrit containers.
-
-* `GERRIT_RAM`: RAM allocated (MiB) to the Gerrit container. `70000` by default.
-* `GERRIT_CPU`: vCPU units allocated to the Gerrit container. `10240` by default.
-* `GERRIT_HEAP_LIMIT`: Maximum heap size of the Java process running Gerrit, in bytes.
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#container.heapLimit)
- `35g` by default.
-* `JGIT_CACHE_SIZE`: Maximum number of bytes to load and cache in memory from pack files.
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#core.packedGitLimit)
- for more details. `12g` by default.
-
-#### LDAP
-
-Configuration values related to LDAP integration.
-See more details [here](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap)
-
-* `LDAP_SERVER`: Mandatory. URL of the organization’s LDAP server to query for user information and group membership from
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.server)
-* `LDAP_USERNAME`: Mandatory. Username to bind to the LDAP server with
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.username)
-* `LDAP_ACCOUNT_BASE`: Mandatory. Root of the tree containing all user accounts
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.accountBase)
-* `LDAP_GROUP_BASE`: Mandatory. Root of the tree containing all group objects
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.groupBase)
-
-#### SMTP
-
-Configuration values related to SMTP integration.
-See more details [here](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail)
-
-* `SMTP_SERVER`: Mandatory. Hostname (or IP address) of a SMTP server that will relay messages generated by Gerrit to end users
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail.smtpServer)
-* `SMTP_USER`: Mandatory. User name to authenticate with
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail.smtpUser)
-* `SMTP_DOMAIN`: Mandatory. Domain to be used in the "From" field of any generated email messages
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail.from)
+* `CLUSTER_DESIRED_CAPACITY`: Optional. Number of EC2 instances composing the cluster. `1` by default.
+* `HTTP_HOST_PORT_MASTER1`: Optional. Gerrit Host HTTP port for master1 (must be different from master2). `9080` by default.
+* `SSH_HOST_PORT_MASTER1:`: Optional. Gerrit Host SSH port for master1 (must be different from master2). `29418` by default.
+* `HTTP_HOST_PORT_MASTER2`: Optional. Gerrit Host HTTP port for master2 (must be different from master1). `9080` by default.
+* `SSH_HOST_PORT_MASTER2:`: Optional. Gerrit Host SSH port for master2 (must be different from master1). `29418` by default.
+* `SLAVE_SUBDOMAIN`: Mandatory. The subdomain of the Gerrit slave. For example: `<AWS_PREFIX>-slave`
+* `LB_SUBDOMAIN`: Mandatory. The subdomain of the Gerrit load balancer. For example: `<AWS_PREFIX>-dual-master`
### 2 - Deploy
diff --git a/master-slave/README.md b/master-slave/README.md
index 3fec46c..efec40b 100644
--- a/master-slave/README.md
+++ b/master-slave/README.md
@@ -60,75 +60,26 @@
### 1 - Configuration
-Each recipe provides a `setup.env.template` file which is a template for configuring the Gerrit stacks.
-Copy that into a `setup.env` and set the correct values for the provided environment variables.
-
-```bash
-cp setup.env.template setup.env
-```
-
-This is the list of available parameters:
+Please refer to the [configuration docs](../Configuration.md) to understand how to set up the
+configuration and what common configuration values are needed.
+On top of that, you might set the additional parameters, specific for this recipe.
#### Environment
Configuration values affecting deployment environment and cluster properties
-* `DOCKER_REGISTRY_URI`: Mandatory. URI of the Docker registry. See the
- [prerequisites](#prerequisites) section for more details.
-* `SSL_CERTIFICATE_ARN`: Mandatory. ARN of the SSL Certificate.
-* `CLUSTER_STACK_NAME`: Optional. Name of the cluster stack. `gerrit-cluster` by default.
* `SERVICE_MASTER_STACK_NAME`: Optional. Name of the master service stack. `gerrit-service-master` by default.
* `SERVICE_SLAVE_STACK_NAME`: Optional. Name of the slave service stack. `gerrit-service-slave` by default.
-* `DNS_ROUTING_STACK_NAME`: Optional. Name of the DNS routing stack. `gerrit-dns-routing` by default.
-* `HOSTED_ZONE_NAME`: Optional. Name of the hosted zone. `mycompany.com` by default.
* `MASTER_SUBDOMAIN`: Optional. Name of the master sub domain. `gerrit-master-demo` by default.
* `SLAVE_SUBDOMAIN`: Optional. Name of the slave sub domain. `gerrit-slave-demo` by default.
-* `GERRIT_KEY_PREFIX` : Optional. Secrets prefix used during the [Import into AWS Secret Manager](#import-into-aws-secret-manager).
- `gerrit_secret` by default.
-* `CLUSTER_DESIRED_CAPACITY`: Optional. Number of EC2 instances composing the cluster. `1` by default.
+* `CLUSTER_DESIRED_CAPACITY`: Optional. Number of EC2 instances composing the cluster. `1` by default.
*NOTE*: if you are planning to run the monitoring stack, set the
`CLUSTER_DESIRED_CAPACITY` value to at least 2. The resources provided by
a single EC2 instance won't be enough for all the services that will be ran*
-#### SPECS
-
-Configuration values to spec up Gerrit containers.
-
-* `GERRIT_RAM`: RAM allocated (MiB) to the Gerrit container. `70000` by default.
-* `GERRIT_CPU`: vCPU units allocated to the Gerrit container. `10240` by default.
-* `GERRIT_HEAP_LIMIT`: Maximum heap size of the Java process running Gerrit, in bytes.
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#container.heapLimit)
- `35g` by default.
-* `JGIT_CACHE_SIZE`: Maximum number of bytes to load and cache in memory from pack files.
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#core.packedGitLimit)
- for more details. `12g` by default.
-
-#### LDAP
-
-Configuration values related to LDAP integration.
-See more details [here](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap)
-
-* `LDAP_SERVER`: Mandatory. URL of the organization’s LDAP server to query for user information and group membership from
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.server)
-* `LDAP_USERNAME`: Mandatory. Username to bind to the LDAP server with
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.username)
-* `LDAP_ACCOUNT_BASE`: Mandatory. Root of the tree containing all user accounts
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.accountBase)
-* `LDAP_GROUP_BASE`: Mandatory. Root of the tree containing all group objects
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.groupBase)
-
-#### SMTP
-
-Configuration values related to SMTP integration.
-See more details [here](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail)
-
-* `SMTP_SERVER`: Mandatory. Hostname (or IP address) of a SMTP server that will relay messages generated by Gerrit to end users
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail.smtpServer)
-* `SMTP_USER`: Mandatory. User name to authenticate with
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail.smtpUser)
-* `SMTP_DOMAIN`: Mandatory. Domain to be used in the "From" field of any generated email messages
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail.from)
+* `PROMETHEUS_SUBDOMAIN`: Optional. Prometheus subdomain. For example: `<AWS_PREFIX>-prometheus`
+* `GRAFANA_SUBDOMAIN`: Optional. Grafana subdomain. For example: `<AWS_PREFIX>-grafana`
### 2 - Deploy
diff --git a/single-master/README.md b/single-master/README.md
index c8a6621..64175a9 100644
--- a/single-master/README.md
+++ b/single-master/README.md
@@ -62,68 +62,15 @@
### 1 - Configuration
-Each recipe provides a `setup.env.template` file which is a template for configuring the Gerrit stacks.
-Copy that into a `setup.env` and set the correct values for the provided environment variables.
-
-```bash
-cp setup.env.template setup.env
-```
-
-This is the list of available parameters:
+Please refer to the [configuration docs](../Configuration.md) to understand how to set up the
+configuration and what common configuration values are needed.
+On top of that, you might set the additional parameters, specific for this recipe.
#### Environment
Configuration values affecting deployment environment and cluster properties
-* `DOCKER_REGISTRY_URI`: Mandatory. URI of the Docker registry. See the
- [prerequisites](#prerequisites) section for more details.
-* `SSL_CERTIFICATE_ARN`: Mandatory. ARN of the SSL Certificate.
-* `CLUSTER_STACK_NAME`: Optional. Name of the cluster stack. `gerrit-cluster` by default.
* `SERVICE_STACK_NAME`: Optional. Name of the service stack. `gerrit-service` by default.
-* `DNS_ROUTING_STACK_NAME`: Optional. Name of the DNS routing stack. `gerrit-dns-routing` by default.
-* `HOSTED_ZONE_NAME`: Optional. Name of the hosted zone. `mycompany.com` by default.
-* `SUBDOMAIN`: Optional. Name of the sub domain. `gerrit-master-demo` by default.
-* `GERRIT_KEY_PREFIX` : Optional. Secrets prefix used during the [Import into AWS Secret Manager](#import-into-aws-secret-manager).
- `gerrit_secret` by default.
-
-#### SPECS
-
-Configuration values to spec up Gerrit containers.
-
-* `GERRIT_RAM`: RAM allocated (MiB) to the Gerrit container. `70000` by default.
-* `GERRIT_CPU`: vCPU units allocated to the Gerrit container. `10240` by default.
-* `GERRIT_HEAP_LIMIT`: Maximum heap size of the Java process running Gerrit, in bytes.
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#container.heapLimit)
- `35g` by default.
-* `JGIT_CACHE_SIZE`: Maximum number of bytes to load and cache in memory from pack files.
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#core.packedGitLimit)
- for more details. `12g` by default.
-
-#### LDAP
-
-Configuration values related to LDAP integration.
-See more details [here](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap)
-
-* `LDAP_SERVER`: Mandatory. URL of the organization’s LDAP server to query for user information and group membership from
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.server)
-* `LDAP_USERNAME`: Mandatory. Username to bind to the LDAP server with
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.username)
-* `LDAP_ACCOUNT_BASE`: Mandatory. Root of the tree containing all user accounts
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.accountBase)
-* `LDAP_GROUP_BASE`: Mandatory. Root of the tree containing all group objects
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#ldap.groupBase)
-
-#### SMTP
-
-Configuration values related to SMTP integration.
-See more details [here](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail)
-
-* `SMTP_SERVER`: Mandatory. Hostname (or IP address) of a SMTP server that will relay messages generated by Gerrit to end users
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail.smtpServer)
-* `SMTP_USER`: Mandatory. User name to authenticate with
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail.smtpUser)
-* `SMTP_DOMAIN`: Mandatory. Domain to be used in the "From" field of any generated email messages
- See [Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#sendemail.from)
### 2 - Deploy
