Merge pull request #5 from memes/enhancement/documentation

Documentation updates, and HA/CFE enhancements

.pre-commit-config.yaml

@@ -1,4 +1,5 @@
 ---
+# spell-checker:disable
 repos:
   - repo: https://github.com/adrienverge/yamllint
     rev: v1.24.2
@@ -8,7 +9,7 @@ repos:
         types: [file, yaml]
         entry: yamllint
   - repo: https://github.com/antonbabenko/pre-commit-terraform
-    rev: v1.32.0
+    rev: v1.39.0
     hooks:
       - id: terraform_fmt
       - id: terraform_docs
@@ -27,6 +28,6 @@ repos:
       - id: sort-simple-yaml
       - id: trailing-whitespace
   - repo: https://github.com/thoughtworks/talisman
-    rev: v1.6.0
+    rev: v1.9.0
     hooks:
       - id: talisman-commit

.talismanrc

@@ -14,14 +14,22 @@ fileignoreconfig:
 - filename: .github/workflows/pre-commit.yml
   checksum: 71fea73f97b2882cc899f729b9e9c2b79cd5a199aecdb9a28794e64d4fda859e
 - filename: modules/big-ip/instance/README.md
-  checksum: 7cc374e7edb7f98530d6f9818820a1549ae20d8c6a9d33bd84e5d16ebc5fb0a0
+  checksum: 4cf9f2888b4c18070c0a1423b50a30f86c3a29f7108f42eaa0f92c95dfde9498
 - filename: modules/big-ip/ha/README.md
-  checksum: 7395be8cbccffa49105fed677227f125ca0631d9bdc17f9f93084ae6eb5b9a37
+  checksum: 0fa3ce279f0cad506a0b69ea3ba515a9ef5971674ddde4f0a2f7889339a4c762
 - filename: modules/big-ip/cfe/README.md
-  checksum: ef06939edac22a49742f6d126f0ce4592ec03cb548224d2ad78bd8a6aaba4b0c
+  checksum: 6fed9e58db1fe307d1a72ff26be5c4736f055fe7dee02b3c99a8f6688bc39713
 - filename: modules/big-ip/cfe/main.tf
   checksum: a3ec435e68eb52f7f43b5694bc6a1d238c86e11d5aab6c92c61459a4daa2199d
 - filename: modules/big-ip/cfe/templates/cfe.json
   checksum: cc3d6ca42066a846a7585bebdc0490c41e1cb996367018ca7461b82725548053
 - filename: modules/big-ip/cfe/files/cloudFailoverExtension.sh
   checksum: 0db34f831d6bb25db19ed2b206c3499766cc4d713e7fe8c611970c556a024251
+- filename: modules/big-ip/README.md
+  checksum: 97024310b64f9e6f08a303ccde837a3815fc5f21099a04be10bdc6036f170d05
+- filename: modules/big-ip/metadata/README.md
+  checksum: 2d33509e132ab8b4754c811892d9d1a6349334ccd87f3cafc9497027f1ec9e70
+- filename: modules/big-ip/cfe/examples/single-project-2nic/main.tf
+  checksum: 290742ecf62a5959de43ff2d1d10b3281a6de1d2631d46fbfda809dac91ad635
+- filename: modules/big-ip/cfe/examples/single-project-3nic/main.tf
+  checksum: bb0c52a41e7f5a002d3676f9f90404cf549a02490a7f69b9cac64bc9cff89cd1

CONTRIBUTING.md

@@ -1,11 +1,11 @@
 # How to contribute
 
-We welcome contributions to this repo, but we do have a few guidelines for
+Contributions are welcome to this repo, but we do have a few guidelines for
 contributors.
 
 ## Open an issue and pull request for changes
 
-All submissions, including those from project memebers, are required to go through
+All submissions, including those from project members, are required to go through
 review. We use GitHub Pull Requests for this workflow, which should be linked with
 an issue for tracking purposes.
 See [GitHub](https://help.github.com/articles/about-pull-requests/) for more details.

README.md

@@ -1,25 +1,49 @@
 # Unofficial F5 Terraform modules for GCP
 
+<!-- spell-checker:ignore markdownlint -->
+<!-- markdownlint-disable MD033 -->
 This repo contains unofficial and unsupported<sup>1</sup> Terraform modules to
 deploy F5 solutions on Google Cloud Platform, using a modular approach that can
 be composed into a solution that is consistent for each variant of a product.
+<!-- markdownlint-enable MD033 -->
 
 > NOTE: The modules **do not** include setup and configuration of supporting
-> resources, such as firewall rules or service accounts.
+> resources, such as ingress firewall rules or service accounts. Where required,
+> the examples will include the bare-minimum setup to show demonstrate usage.
+> Some modules will include links to other public GitHub repositories that
+> demonstrate specific use-cases.
+
+## Rationale
+
+The intent is allow for integration of BIG-IP, NGINX+, and other F5 products
+with GCP infrastructure that is managed using Google's
+[Cloud Foundation Toolkit](https://cloud.google.com/foundation-toolkit)
+Terraform modules or an equivalent. These are not fully-baked solutions, but can
+be integrated to build a reusable deployment pipeline.
+
+For example, the modules do not include ingress firewall rule resources as core
+module components. This is because some organizations may mandate use of service
+account based rules, where others prefer tag based, or a combination of both where
+interfaces are attached to peered VPCs. The exception to this is the firewall
+module to support ConfigSync for HA and CFE clusters; since the BIG-IPs will be
+deployed to the same VPC networks, it is reasonably safe to assume a service
+account based rule will be universally applicable.
 
 ## BIG-IP
 
-The BIG-IP modules build on each other to have a similar API (Terraform input
-variables), promoting consistency and reuse.
+The [BIG-IP](modules/big-ip) modules build on each other to have a similar AP
+(implemented as Terraform input variables), promoting consistency and reuse. For
+more information about these open the README files in each module.
 
 1. [x] [Standalone](modules/big-ip/instance/) BIG-IP instances
    * [x] Support 1-8 network interfaces
    * [x] Opinionated startup scripts
-   * [x] Specify default gateway for
+   * [x] Override default gateway when needed; e.g. for bootstrapping in a restricted
+         VPC where data-plane does not have egress.
    * [x] [AS3](https://clouddocs.f5.com/products/extensions/f5-appsvcs-extension/latest/) support
    * [x] [DO](https://clouddocs.f5.com/products/extensions/f5-declarative-onboarding/latest/) support
-2. [x] [HA](modules/big-ip/ha/) BIG-IP instances
-   * [ ] [CFE](https://clouddocs.f5.com/products/extensions/f5-cloud-failover/latest/) Cloud Failover Extension support
+2. [x] [HA](modules/big-ip/ha/) BIG-IP clustered instances
+   * [x] [CFE](modules/big-ip/cfe/) [Cloud Failover Extension](https://clouddocs.f5.com/products/extensions/f5-cloud-failover/latest/) support
 3. [ ] Autoscaling
 4. [ ] WAF
 5. [ ] GKE integration with [CIS](https://www.f5.com/products/automation-and-orchestration/container-ingress-services)
@@ -34,5 +58,7 @@ TBD
 
 ---
 
+<!-- markdownlint-disable MD033 -->
 <sup>1</sup>This repo will be maintained on a best-effort basis, but is not a
 substitute for F5 support.
+<!-- markdownlint-enable MD033 -->

foundations/README.md

@@ -1,4 +1,4 @@
 # Foundations
 
-This module is used to setup multiple networks for testing the F5 modules. It is
-not needed for consumers of the modules.
+This module is used to setup multiple networks for testing the published modules.
+It is not needed for consumers of the modules.

modules/big-ip/README.md

@@ -0,0 +1,43 @@
+# BIG-IP modules
+
+<!-- spell-checker:ignore markdownlint, NICs, secretmanager -->
+These modules support deploying BIG-IP v13, v14, and v15 instances to Google Cloud
+in an opinionated manner. By themselves they do not implement a full stack or
+solution, and additional setup will be needed for firewall rules, service account
+creation and role assignments.
+
+## Dependencies
+
+The BIG-IP modules all have a common set of requirements.
+
+1. Terraform 0.12
+
+   A future version of these modules will target Terraform 0.13 once the majority
+   of module consumers request it.
+
+2. Google Cloud [Secret Manager](https://cloud.google.com/secret-manager)
+
+   There are many good options for run-time secret injection but this module is
+   supporting Google's Secret Manager only at this time.
+
+3. APIs to enable
+
+   * Compute Engine `compute.googleapis.com`
+   * Secret Manager `secretmanager.googleapis.com`
+   * Storage (required for CFE) `storage-api.googleapis.com`
+
+## Run-time setup
+
+The BIG-IP modules in this repo support [cloud-init](https://cloudinit.readthedocs.io/en/latest/)
+and [metadata-startup-script](https://cloud.google.com/compute/docs/startupscript)
+boot options, defaulting to the metadata startup-script for compatibility with
+BIG-IP versions 13.x, 14.x, and 15.x. Set the `use_cloud_init` input variable to
+`true`.
+
+Fundamentally both approaches launch the same shell scripts; the difference is
+that `cloud-init` script installs a systemd service unit with dependencies to
+prevent early execution, and automatically disables the service unit after
+success. The simple metadata startup-script will execute on every boot.
+
+For more information on how run-time configuration is applied to each BIG-IP
+instance, see the [configuration details](metadata#configuration) section in [metadata module](metadata).