Overview

You can generate the Terraform and Python files needed to configure a Sym Flow with symflow generate!

This command must be run inside of the directory created by symflow init, and it will prompt you for the information needed to set up your Sym Flow. Most resources will differ based on the chosen type of Flow, but commonly there will be:

• A file containing the sym_flow resource
• An impls directory containing the Python implementation files for your Flows
• A connectors.tf file that connects Sym to your AWS Account
• A secrets.tf file that allows Sym Runtime to access secrets in AWS Secrets Manager

sym_flow

The Terraform configuration of a sym_flow can be broken down into two parts:

The basics

resource "sym_flow" "this" {
  name  = "approval-galaxy"
  label = "Galaxy Transfer"

  implementation = file("${path.module}/impls/approval_impl.py")
  environment_id = sym_environment.this.id
  
  vars = {
    auto_approve = "[email protected]"
  }
  ...
}

The basic configuration of a sym_flow includes:

The prompt fields

Different types of access requests need different types of data. That's why Flows support custom fields in the request modal! We've kept it fairly basic here with just two generic questions— "which galaxy" and "why"— but fields can be as specific as needed. Check out Prompt Fields for more information.

resource "sym_flow" "this" {
  ...

  params {
    # Each prompt_field defines a custom form field for the Slack modal that
    # requesters fill out to make their requests.
    prompt_field {
      name = "galaxy-name"
      label = "Which galaxy would you like to travel to?"
      type = "string"
      required = true
      allowed_values = ["Andromeda Galaxy", "Triangulum Galaxy", "Wolf–Lundmark–Melotte"]
    }

    prompt_field {
      name = "reason"
      label = "Why would you like to go?"
      type = "string"
      required = true
    }
  }
}

impls/

A folder that houses all the impl.py files. symflow generate will generate a new impl.py file per Flow, but you may choose to reuse implementations across Flows if you so choose.

The impl.py Python Implementation

Now that the sym_flow resource is configured, all that's left is to write its impl.py. This is where Sym's Python SDK can be used to customize your Flow's logic.

The first thing we'll need in the impl.py is a get_approvers reducer. This is the only required part of an impl.py, and it tells Sym where to send access requests in Slack:

# First, we'll import everything we need for this impl.py
from sym.sdk.annotations import reducer
from sym.sdk.integrations import slack

# Then, we add our first reducer! `get_approvers` will be used any time a request
# is made in Sym.
@reducer
def get_approvers(event):
    """Route Sym requests to a specified channel."""

    # Make sure that this channel has been created in your workspace!
    return slack.channel("#sym-requests", allow_self=True)

While get_approvers is the only required function in the impl.py, there are many other hooks that you can implement.

connectors.tf

If you generated a Flow that requires Sym to interact with your AWS account, such as okta or aws-iam, then a connectors.tf file will be generated for you. This file contains the AWS resources needed to allow Sym to perform actions in your AWS account. For more details, see Connecting Sym to AWS.

secrets.tf

If you generated a Flow that interacts with a third-party service that requires authentication, such as okta, then a secrets.tf file will be generated for you. This file contains the Terraform module needed to allow Sym to read secrets from your AWS Secrets Manager. For more details, see Manage Secrets with AWS Secrets Manager.

Testing in Slack

Almost there! All the Terraform configuration is now written, all that's left to do is test it out. We'll start by applying the Terraform:

$ terraform init

Initializing the backend...
Initializing provider plugins...
Terraform has been successfully initialized!

$ terraform apply

sym_integration.slack: Creating...
sym_integration.slack: Creation complete after 1s [id=2127a917-f92b-491a-ba63-6556734b152c]
sym_error_logger.slack: Creating...
sym_error_logger.slack: Creation complete after 0s [id=358fa690-c5bb-457e-9527-ef5aad12a542]
...

Once the terraform apply is done:

1. Go to the Slack workspace you installed Sym in
2. Type /sym anywhere

You should see your very first Sym Flow:

Next steps

Nice job! You should have a Sym Flow up and running. Now that you've got the basics down, there are a ton of ways to tailor Sym to your organization's needs. To learn more, check out:

• Integrated Services - Learn how Sym can automatically grant or escalate access to external services like AWS, Okta, and Aptible.
• Approval workflows-as-code - Learn how to customize the impl.py to fit your specific rules using our Python SDK.
• Reporting and audit - Learn how to get structured logs for all access requests and set your organization up for audit success via our Reporting framework.

📘

Check out our Examples Repo for end-to-end examples

If you're looking for some fully-baked samples of working Sym Flows, head over to our Examples Repo!