Stack design

Hub CLI manifest is flexible format that could be overused. Please follow the guidelines below.

Components

1. Component's hub-component.yaml must not use fromEnv: to bind kind: user parameters to the environment variables. The parameters are bound to the environment (if required) on stack level - either in hub.yaml or params*.yaml.
2. Export parameters to OS environment via env:
3. Set defaults via value:.
4. kind: user is for high-level input from user, like domain of the stack, number of worker nodes, etc.
5. default: is for kind: user - if no value is specified, then - if stdin is a TTY - user is asked by Hub CLI to accept the default or provide value. If not a TTY, then the default is used as value.
6. Set defaults in Makefile or deploy shell script, e.g. NAME ?= dev, so that the component is usable out of CLI lifecycle (modulo templates), and also self-documented.
7. Do not rely on global environment set prior to stack deployment, e.g. TF_VAR_name. They will be filtered out from environment by Hub CLI. See help for hub deploy --os-environment.
8. Component parameters defined in hub-component.yaml (implicit kind: tech) are scoped to the current component only. Use outputs: to provide values visible by subsequent components, for example:

outputs:
- name: component.postgresql.namespace
- name: component.postgresql.instance
  value: ${component.postgresql.name}-rds

9. To bind hub.yaml level parameter to a value which is not known in advance (component output) use kind: link:

parameters:
- name: component.cdn.bucket
  value: ${component.s3.bucket}
  kind: link

Name

1. <component> is origin from components/<component> of Agile Stacks components Git repo.
2. <component-name> is the name of the component in the stack (pg1) - same as ${hub.componentName}:

components:
- name: pg1
  source:
    dir: components/postgresql-rds

3. Finally, component.*.name - if required for particular component implementation to avoid collisions and describe the deployment, is something user may want to set, and may become TF_VAR_name, Kubernetes ingress name, etc. on the component level. You may want to default it to ${hub.componentName} in hub-component.yaml.

For Terraform-based components the shared state is stored as s3://state-bucket/<domain>/<component>/<component-name>/terraform.tfstate.

Stack

1. Bind stack instance specific parameters to environment variables via fromEnv: so that stack template could be deployed multiple times, and parameterized via environment.
2. Avoid fromEnv: TF_VAR_*.
3. Avoid setting env: - the parameters must be exported by each component in component specific way. This is actually currently disabled by Hub CLI.

Envrc

1. Avoid setting TF_VAR_* variable to influence component directly bypassing hub.yaml / params*.yaml wiring. Hub CLI will filter these out of children process environment by default --os-environment.
2. Set .envrc and/or .env vars for hub.yaml / params*.yaml parameters captured via fromEnv.