Revamp Terraform template

[jcbhmr]

The Terraform template is now:

1. More generic. There's not as many options. This is a potentially controversial idea. If we want more options, that's OK. See below for discussion on this change.
2. v2.0.0
3. Named "terraform" instead of "terraform-basic". If we need a future differentiator between Terraform and Terraform (basic), then we can rename it again. So far, though, the need has not arisen for two Terraform templates (so far).
4. Encourage users to select a different base image instead of piling on things to the features area.
5. Removed the README.md in the src folder that was autogenerated from the GitHub CI stuff. Instead, I propose we create a GitHub Pages site (see below) (SEPARATE PR)

All of these things below are OPINIONS of @jcbhmr, not FACTS and don't necessarily represent all of @devcontainers-contrib

Why we should encourage changing the base image instead of piling on features

1. Build times

When you first build a devcontainer image (when you click "New codespace on main" in GitHub) if you have a base image, all it needs to do is copy files. When you have a feature, it needs to run shell commands to compile, install, download, move, etc. This is GOOD for things that are ADDONS, but not for CORE THINGS like Node.js that already have an image.

For instance:

{
  "image": "mcr.microsoft.com/devcontainers/base",
  "features": {
    "ghcr.io/devcontainers/features/terraform": {},
    "ghcr.io/dhoeric/features/terraform-docs": {},
    "ghcr.io/devcontainers/features/docker-in-docker": {},
    "ghcr.io/devcontainers/features/python": {},
  }
}

vs

{
  "image": "mcr.microsoft.com/devcontainers/python",
  "features": {
    "ghcr.io/devcontainers/features/terraform": {},
    "ghcr.io/dhoeric/features/terraform-docs": {},
    "ghcr.io/devcontainers/features/docker-in-docker": {},
  }
}

The python image one is way faster. It doesn't need to rebuild Python from source.

2. It makes more semantic sense

It seems like Terraform should be an addon. You have this Python or JS project, and you want to deploy it with infra. So what do you do: a) configure it yourself or b) add a terraform config and install terraform. That's an addon right there! It's a critical project addon, but an addon nonetheless.

Why we should use a GitHub Pages site for docs generation

See #10

Why I think it's a good idea to keep options to a minimum in the devcontainer-template.json

This section is very rant-like

Not knowing what the heck an option does isn't good UX

Even the official C++ template kinda has this issue. IDL what the CMake option even does!

Ideally you should be able to get started in a few clicks and be done. Even having the features popup every time is a bit daunting. I just want to create something from a one-click template lol!

At the very least, we need some defaults. The Terraform version prompt when you just hit enter (cause you don't know what it means) just cancels the whole thing. There's no like pattern, suggestions, etc. at all.

I think it's best if we just axe this for now and re-add it if we later deem it a good idea. So far, I have never really wanted to change the defaults. I just want to:

1. Create GitHub repo named my-awesome-project
2. Open it in codespaces
3. Create a devcontainer config file
4. Write code.

That's it. No "choose which version of CMake" well DUH I want the latest one, this is a new project! Sure, I might want to edit the file later and customize it, but I just want a one-click thing for now.

What's the deal with the // 💡 Replace this image with your preferred base project image! thing?

Ideally, a user would use a Node project and then choose the Terraform feature in the features prompt

But most users don't do that. So we have a template for them! We default to the UNIVERSAL image to cover most cases, but encourage users to change it.

This is basically just me re-iterating what I said in "Why we should encourage changing the base image instead of piling on features"

[jcbhmr]

@danielbraun89 Waiting on your opinions before merging this.

[danielbraun89]

What is the main benefit you see from removing the options though? Is it to save clicks in the template creation phase? Do they require another click even if they have defaults?

Thing is, the target user I have envisioned for this template was not a beginner but rather an experienced terraform user, for which it will save the time and hussle to search for all terraform features he expects, and serves as a one stop shop for the ecosystem of terraform development. This is a kind of user who might appreciate the ability to pinpoint versions of terraform tools, tools versioning is conservative and important in the gitops fields (mostly only upgrade a version if they have to)

[jcbhmr]

/re @danielbraun89

What is the main benefit you see from removing the options though? Is it to save clicks in the template creation phase? Do they require another click even if they have defaults?

This is correct. Each option will prompt you, even if it has a default. This is good when it's a very high-level important option like "Which Python package manager do you want to use? Poetry, pip, or pdm?" but doesn't work so well when it's a supplementary option.

In this particular instance: when I'm creating a project that uses Terraform, I don't need to choose a place to store Terraform logs. BUT in the devcontainer.json that gets generated, you could have a commented out section (kinda like the VS Code authored templates to now) which says something like:

// 💡 Un-comment this if you want to store the Terraform logs to a file.
// "remoteEnv": {
//   "TF_LOG": "...",
//   "TF_LOG_PATH": "..."
// }

Here's the thing I'm using as a reference from the VS Code devcontainer template for Python:

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/python
{
	"name": "Python 3",
	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
	"image": "mcr.microsoft.com/devcontainers/python:0-${templateOption:imageVariant}"

	// Features to add to the dev container. More info: https://containers.dev/features.
	// "features": {},

	// Use 'forwardPorts' to make a list of ports inside the container available locally.
	// "forwardPorts": [],

	// Use 'postCreateCommand' to run commands after the container is created.
	// "postCreateCommand": "pip3 install --user -r requirements.txt",

	// Configure tool-specific properties.
	// "customizations": {},

	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
	// "remoteUser": "root"
}

Thing is, the target user I have envisioned for this template was not a beginner but rather an experienced terraform user, for which it will save the time and hussle to search for all terraform features he expects, and serves as a one stop shop for the ecosystem of terraform development. This is a kind of user who might appreciate the ability to pinpoint versions of terraform tools, tools versioning is conservative and important in the gitops fields (mostly only upgrade a version if they have to)

That's OK! Maybe a terraform-advanced template would work? That or a compromise between some version options and/or maybe some in-JSON comments that indicate where to put specific pinned versions? I guess I was interpretting "terraform-basic" to be the basic Terraform template (hence the minimal options).

Thoughts? Comments? Ideas?

[jcbhmr]

Given that this organization seems to be just "danielbraun98's devcontainers stash" instead of a Community Devcontainers organization, I think that you're right, you are justified to keep the Terraform template as-is.

This fits with to the discussion in https://github.com/devcontainers-contrib/features/issues/316 where it seemed to be indicated that this was "as though" it were danielbraun98/devcontainer-features. I assume that this is also designed as a for-you-by-you template to fit your particular use case.