This repo contains folders of end-to-end examples containing the minimally necessary Terraform and impl.py
files to configure a specific Flow.
This document describes a set of steps for how to create a structurally consistent example.
- An example should be tightly scoped to the feature it is exemplifying.
- If possible, there should only be one
main.tf
containing the entire Terraform configuration. - Each example should be contained in its own folder, named with underscores (i.e.
okta_access_strategy
)
README.md
should have:- A title with a descriptor of the example, e.g.
Okta Access Strategy
. - 1-2 sentence description of what the Flow does.
- A short screen recording, if possible.
- See the
okta_access_strategy/README.md
for an example.
- A title with a descriptor of the example, e.g.
impl.py
- The minimal
impl.py
needed for the example to run.
- The minimal
main.tf
- The minimal Terraform needed to configure the Flow.
- If the file exceeds 300 lines, then you can consider breaking it up into multiple files.
- The minimal Terraform needed to configure the Flow.
versions.tf
- The minimally required providers for the example.
- Implement your example in a new folder
- Add a README.md. You can use the
basic/approvals
README.md as a template - Add a screen recording to your example's README.md
- Run
terraform fmt
- Commit your example
- Add a row to the Content table in the root directory's README.md.
- Make sure the table is in alphabetical order (i.e. the same order as the folders).
- Avoid variables unless they are absolutely necessary, this helps make examples easily understandable at a glance.
- Comment each resource describing what it does.
- Structure the order of the resources so that if
resource-A
referencesresource-B
, thenresource-B
is declared first.- e.g. if
sym_integration
needs asym_secret
, thesym_secret
should be declared first.
- e.g. if
- Recommended order of resources:
- AWS Secrets Manager resources
- Secrets & Sym Integrations
- Access Targets
- Access Strategy
- Flow
- Basic Environment Configuration
- Local Testing:
override.tf
files are special Terraform files that overridemain.tf
. This file is gitignoredmain.tf
should be written with everything you intend to commit in the example, and if you need to override something, redefine it inoverride.tf
and change what needs to be changed.- For example:
# main.tf
resource "sym_integration" "slack" {
type = "slack"
name = "main-slack"
# For your main.tf, use an example Workspace ID
external_id = "T123ABC"
}
# override.tf
resource "sym_integration" "slack" {
type = "slack"
name = "main-slack"
# In override.tf, use your actual workspace ID
external_id = "T0123DCL4WW"
}