Verified Commit a80eabae authored by MrMan's avatar MrMan
Browse files

Fix typos in README, expand on kustomize/envsubst usage

parent a5e4c15a
......@@ -10,7 +10,7 @@ This repository serves as what a `-infra` repo might look like for a time manage
A few changes have been made to this pattern, and major ones are listed below
## Using `kustomize` has been used instead of `envsubst` (06/02/2020) ##
## Using `kustomize` as an alternative to `envsubst` (06/02/2020) ##
In [working on recent projects](https://vadosware.io/post/setting-up-mailtrain-on-k8s/#step-1-figure-out-how-to-integrate-kustomize-for-templating-with-the-makeinfra-pattern), the `kubectl` official endorsement of `kustomize` made it a lot easier to replace `envsubst` (which is a much more general low-level tool) with a more abstracted and tailored tool like `kustomize`. There are lots of options in the k8s space for templating and `kustomize` was one of my favorites to begin with, and once I got used to using it, it made sense to employ.
......@@ -67,7 +67,7 @@ The core ideas of the `MakeInfra` pattern are simple:
- **Name resource definitions with descriptive suffixes** - i.e. `jaeger.deployment.yaml`, `monitoring.ns.yaml`
- **Use a `Makefile` with `.PHONY` targets** in the folder with your resource definitions
- **Use [`git-crypt`](https://www.agwa.name/projects/git-crypt/) to store credentials inside the `-infra` repo** - for testing, staging, and maybe even production, right in the repo.
- **Suffix files that must be transformed with `.pre`** - This makes it pretty clear to anyone which files are ready and which are not -- you can also use whatever tool you want (KSonnet, `envsubst`, `m4`, `python`) for replacement.
- **Suffix files that must be transformed with `.pre`** - This makes it pretty clear to anyone which files are ready and which are not -- you can also use whatever tool you want (`kustomize`, `envsubst`, `m4`, `python`) for replacement.
- **Use the tools that make sense for your team** - just like you would for any other `Makefile` powered project (so technically, you can use `helm`, or `jinja2`, or raw `perl`, or `ksonnet` whatever else)
**I think this idea is more powerful than tools helm because it's a superset of the ideas behind helm (as in you can use helm very easily with this approach), and it decomposes well enough to offer a subset of the features offered by a tool like helm when you're starting o\
......@@ -81,15 +81,14 @@ When you want to ensure the project is up, if your local `kubectl` is already pr
Rather than hard-coding various dynamic variables (e.g. server to aim at, version of software to deploy) into files, it's obvious to allow for some small amount of dynamism when configuring your infrastructure.
**The `MakeInfra` pattern suggests that you use [`envsubst`](https://www.gnu.org/software/gettext/manual/html_node/envsubst-Invocation.html) (or another similar) tool to solve this problem. In addition to using a software like `envsubst`, it is suggested that you use a consistent naming pattern, like suffixing all files that require building with `.pre` to indicate that they must be built**. The idea here is to make it very obvious when you use files that they must be run through some sort of transformation tool first. It is important to also include the necessary `Makefile` targets to ensure the user doesn't need to know too much about **how** the file is built, but just that they can run something like `make file.extension` and the file will get made as it should.
**The `MakeInfra` pattern suggests that you use [`kustomize`](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization) or [`envsubst`](https://www.gnu.org/software/gettext/manual/html_node/envsubst-Invocation.html) (or another similar) tool to solve this problem. In addition to using a software like `kustomize`/`envsubst`, it is suggested that you use a consistent naming pattern, like suffixing all files that require building with `.pre` to indicate that they must be built**. The idea here is to make it very obvious when you use files that they must be run through some sort of transformation tool first. It is important to also include the necessary `Makefile` targets to ensure the user doesn't need to know too much about **how** the file is built, but just that they can run something like `make file.extension` and the file will get made as it should.
As mentioned earlier, you are free to use another simliar tool, or full blown programming language to solve this problem, it just happens that `envsubst` is a relatively simple tool, and if simple substitution is largely your usecase, it should be very beneficial.
As mentioned earlier, you are free to use another simliar tool, and the two tools that are currently recommended are recommended for the following reasons:
See: The `todo` app folder itself provides an example. You can try it yourself in the command line by running the following:
- `kustomize` - good kubernetes-specific paradigms/abstractions, able to recognize k8s structure and perform more intelligent tasks like generating secrets
- `envsubst` - extremely simple off the shelf unix tool, excellent for simple substitution
```
$ make todo/v1.0/deployment.yaml # alternatively, `cat todo/v1.0/todo.deployment.yaml.pre | REPLICA_COUNT=3 envsubst > todo.deployment.yaml`
```
See: The `todo` app folder itself provides an example of `kustomize` while the related `postgres` requirement under `persistence` offers an example of using `envsubst`. Check the `Makefile` for more details (`todo/v1.0/Makefile` and `todo/v1.0/persistence/v1.0/postgres/Makefile`).
## Secrets ##
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment