Hello World

Looks like you have installed tc and understood the concepts and features in abstract. They will become clearer to you as you start playing with tc. Let’s jump in and try a hello world topology. We’d like to define a HTTP GET route backed by a serverless function that returns a message. Common usecase right ?

1. Define Topology

   mkdir hello-world
   cd hello-world

   Add the following topology.yml file:

   topology.yml

   name: hello-world
   
   routes:
    /hello:
      method: GET
      function: responder

2. Implement responder function

   For this example, let’s write it in python (I know!).

   tc scaffold
    > Function name: responder
    > Function kind: Namespaced
    > Select language: python3.12
    > Select dependency mechanism: None
    > Select format:  YAML
    > Override default runtime parameters (roles, vars) ? No

   • topology.yml
   • Directoryresponder

     • handler.py

3. Create sandbox

   Let’s create our first sandbox called yoda and use a dev AWS_PROFILE (You can use any profile that is convenient to you).

   tc create -s yoda -e dev

   

   curl https://kg51px0mi8.execute-api.us-west-2.amazonaws.com/hello
   => {"message": "hello world"}

Congratulations! You have designed, built and deployed your first functor on your own sandbox.

Optional Overrides

Perhaps, you’d like to increase the memory or reduce the timeout. Now add an infra directory

topology.yml

name: hello-world
infra: ./infra

routes:
  /hello:
    function: responder

We can override the defaults by specifying the roles, vars, schemas etc in the specified infra directory.

• topology.yml
• Directoryresponder

  • handler,py
• Directoryinfra

  • Directoryvars

    • responder.json
  • Directoryroles

    • responder.json

infra/vars/responder.json

{
  "default": {
    "environment": {
      "LOG_LEVEL": "INFO",
       "MY_KEY": "ssm://path/to/secret"
    },
    "timeout": 260,
    "memory_size": 128
  },
  "yoda": {
    "timeout": 300,
    "memory_size": 256
  }
}

Note the ssm:/ uri in certain values. These secrets are fetched from the URI when creating or updating the sandbox.

infra/roles/responder.json

{
  "Statement": [
    {
      "Action": [
        "dynamodb:GetItem"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:dynamodb:{{region}}:{{account}}:table/my-table",
        "arn:aws:dynamodb:{{region}}:{{account}}:table/my-table/*"
      ],
      "Sid": "AllowAccessToDynamoDB"
    }
  ]
}

You can override the generated IAM permissions by specifying the role and policy in the infra path. The policy is also templated and can be rendered in any profile, account or sandbox.

The following will update the runtime vars for the functions - in this case responder.

tc update -s yoda -e dev -c functions/vars
tc update -s yoda -e dev -c functions/roles

# or just
tc update -s yoda -e dev -c functions

Behind the scenes

tc composed, resolved and created the sandbox when we did a tc create -s yoda -e dev. Composing involves building the graph of all the specified entities and generating all the infrastructure components, permissions etc required to connect the entities in a sandbox. Note that none of the infrastructure information was leaked into the topology definition.

tc picked the default provider (AWS Serverless) and mapped routes to API Gateway routes, built the function for Lambda, generated the IAM policies/roles and created the entities in the right order by traversing the graph.

Optionally, we also saw how we can override the generated infrastructure boilerplate as needed. tc will overlay the defaults and the augmented infrastructure components.

Next Steps

This of course is a very simplistic view of tc. You may want to say more than hello to the world. Give this Example a try!