doc improvement: clarify intended usage and level of support

eeaton commented 2 months ago

TL;DR

This repo is intended to be forked into the user's own environment, then customized and maintained in their own version control system. We do not intend to support use cases that use this repo as a remote reference. However, this has not been clearly documented.

I will add documentation throughout the repo to make it more clear about what we intend to support:

This repo is a public example of code to deploy resources aligned to best practices in the [Enterprise foundation blueprint]s semantically valid
Code is semantically valid, pinned to known good versions, and passes terraform validate and lint checks
The actual resource deployment passes CI tests before merging that confirm the resources can deploy as intended.

And what we do not intend to support:

using this repo as a remote reference
the ability for a customer environment to do in-place upgrades between repo versions after they have customized the code and deployed other resources on top
support for all versions and customizations that a user might tweak in their own environment

Terraform Resources

n/a

Detailed design

n/a

Additional information

https://github.com/terraform-google-modules/terraform-example-foundation/issues/1167 is a good example of why we need to set expectations on the intended usage and level of support.

mromascanu123 commented 2 months ago

Almost any open source project provides a functional baseline that one can use as is and obviously, if need be, customize. But in most cases there is no need to customize because the consumers audience of such a OSS distro find the baseline functionality more than sufficient. And no specific support for normal / common usage is needed except in very special cases. TEF is an exception and it seems the project is geared at strong development teams rather than end-users. Because as-is a TEF deployment is unusable for real-life use scenarios and is indeed just an example of how to use the TF modules. This is a major issue for a majority of would-be adopters of the Google Landing Zone – very few (and large) organizations have the capacity to re-develop TEF or engage PSO to do it, and most organizations would simply go with another provider’s turn-key landing zone, be it Azure, AWS or Oracle, which have much lower barriers to adoptions and can be used as-is for most common use scenarios just by tweaking simple configurations (yaml files in case of AWS LZA, vargroups for Azure).

Maybe need to think in the short term to a way of adapting TEF to become usable as-is and customizable if needed, and this via a mechanism of configurability making the code mostly immutable and deployment for most common use scenarios data-driven e.g. via yaml config files just like AWS LZA.

eeaton commented 3 weeks ago

Addressed by PR #1276.

And, followup to the comment from May 16 that I previously overlooked:

We're in agreement that it is unrealistic for this repo to be used exactly as is. Our target audience of highly complex enterprise organizations in regulated industries will inevitably require customization, visibility, and control over many design aspects; we assume that they have a cloud platform team with the skills and responsibility to do this (whether in-house or with partner support). This is a contradictory goal to a turnkey solution.

In cases that want a turnkey solution, you might be interested in Google Cloud setup, a guided console-based experience that assumes less prerequisite cloud knowledge and no hands-on coding required. However, by design that tool covers a much simpler scope of features, and does configures foundation features only (no guidance on day 2 operations like guidance on automating through CICD pipelines, modifying the foundation in the future, deploying workloads to the foundation, still assumes that privileged humans create resources directly, etc).

The two tools have different goals and different audiences: as simple as possible but limited scope of control and customization, or some design/engineering effort required but able to address a much more comprehensive scope of control and customization.

I'll close this issue for now, please reopen if you think it needs further discussion.

mromascanu123 commented 3 weeks ago

Not sure about the completion criteria having been relied upon to "complete" the fundamental issue raised in my comment. Unless by technical and business design the TEF distribution is intended to be unusable, as stated in the closure comment. But instead of burning cycles on esthetics (e.g. renaming non-production to nonproduction) nothing would stop the TEF development team from refactoring the TEF distribution e.g. adding ("as an example" if more appropriate) a basic configurability mechanism replacing the annoying hardcoded "example" code (addressing scheme, regions, etc). This was raised by #1152 , #1153,, #1154, #1155 and #1226. It would be also more useful, even for an example, to fix the bugs raised in #1228 , #1240 and #1269.

eeaton commented 2 weeks ago

I'm happy to discuss feedback or contributions, but the rude and sarcastic comments are unnecessary.

Allow me to expand on my reasoning why I think a turn key solution is neither a realistic nor a valuable goal for this repo:

The blueprint can accelerate design and build by addressing general best practice design recommendations and undifferentiated heavy lifting, but we assume that the target audience (complex enterprises) are going to review the recommendations made against their unique requirements and customize.
There is no one size fits all solution for enterprise customers. Every foundation engagement I've had with enterprise customers has deviations from the generalized best practices, based on their specific separation of duties among teams, accommodating their existing estate, model of treating cloud as a unique environment or an extension of onprem, dependencies on existing monitoring and security tools, willingness to adopt cloud networking and security models, risk appetite, etc.
Turnkey solutions like Google Cloud Setup have a much more limited scope of what they enable: this can be a great option for a customer who says "just get me started with a recommended folder and VPC". However, this level of simplicity is not viable for Enterprise customers or regulated industries.
Competitor solutions like AWS Landing Zone accelerator are a different scope than this repo, but have a similar design philosophy: "While these assets can help you reduce the effort required to manually build a production-ready infrastructure, you will still need to tailor them to your unique business needs. "

I agree that hardcoded IP and other bugs should be improved, but those are different topics than this issue. The 4 separate instances of IP ssues you raised are consolidated into #1226, and we've triaged this for the major redesign work planned for v5 later in the year, which will include some other significant network refactoring not published to the public issue tracker. The other bugs you linked are triaged to address as part of the backlog. If you have context on why a particular issue needs more urgent attention, please add the details to the relevant issue.

terraform-google-modules / terraform-example-foundation