From 458bba40e0ac69b39e74c363f7fc3661e45e5044 Mon Sep 17 00:00:00 2001
From: fujiwara <fujiwara.shunichiro@gmail.com>
Date: Wed, 28 Aug 2024 15:10:52 +0900
Subject: [PATCH] add Jsonnet native functions into Readme

---
 README.md | 118 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 100 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index ba5fd0b..8cd8ffa 100644
--- a/README.md
+++ b/README.md
@@ -63,7 +63,7 @@ jobs:
     steps:
       - checkout
       - lambroll/install:
-          version: v1.0.1
+          version: v1.1.0
       - run:
           command: |
             lambroll deploy
@@ -398,6 +398,11 @@ function.json is a definition for Lambda function. JSON structure is based from
   }
 }
 ```
+
+The template functions is available in `{{ }}`.
+- `env` function expands environment variables.
+- `must_env` function expands environment variables. If the environment variable is not defined, lambroll will panic and abort.
+
 #### Tags
 
 When "Tags" key exists in function.json, lambroll set / remove tags to the lambda function at deploy.
@@ -415,6 +420,33 @@ When "Tags" key exists in function.json, lambroll set / remove tags to the lambd
 When "Tags" key does not exist, lambroll doesn't manage tags.
 If you hope to remove all tags, set `"Tags": {}` expressly.
 
+### Jsonnet support for function configuration
+
+lambroll also can read function.jsonnet as [Jsonnet](https://jsonnet.org/) format instead of plain JSON.
+
+```jsonnet
+{
+  FunctionName: 'hello',
+  Handler: 'index.handler',
+  MemorySize: std.extVar('memorySize'),
+  Role: 'arn:aws:iam::%s:role/lambda_role' % [ std.extVar('accountID') ],
+  Runtime: 'nodejs20.x',
+}
+```
+
+```console
+$ lambroll \
+    --function function.jsonnet \
+    --ext-str accountID=0123456789012 \
+    --ext-code memorySize="128 * 4" \
+    deploy
+```
+
+- `--ext-str` sets external string values for Jsonnet.
+- `--ext-code` sets external code values for Jsonnet.
+
+v1.1.0 and later, lambroll supports Jsonnet native functions. See below for details.
+
 #### Expand SSM parameter values
 
 At reading the file, lambroll evaluates `{{ ssm }}` syntax in JSON.
@@ -427,6 +459,19 @@ For example,
 
 SSM parameter value of `/path/to/param` is expanded here.
 
+For Jsonnet, the `ssm` function is available.
+
+```jsonnet
+local ssm = std.native('ssm');
+{
+  Environment: {
+    Variables: {
+      FOO: ssm('/path/to/param'),
+    },
+  },
+}
+```
+
 #### Expand environment variables
 
 At reading the file, lambroll evaluates `{{ env }}` and `{{ must_env }}` syntax in JSON.
@@ -457,6 +502,21 @@ Environment variable `FOO` is expanded. When `FOO` is not defined, lambroll will
 }
 ```
 
+For Jsonnet, the `env` and `must_env` native functions are available.
+
+```jsonnet
+local env = std.native('env');
+local must_env = std.native('must_env');
+{
+  Environment: {
+    Variables: {
+      FOO: env('FOO', 'default for FOO'),
+      BAR: must_env('BAR'),
+    },
+  },
+}
+```
+
 #### Environment variables from envfile
 
 `lambroll --envfile .env1 .env2` reads files named .env1 and .env2 as environment files and export variables in these files.
@@ -491,7 +551,7 @@ data "aws_iam_role" "lambda" {
   "Handler": "index.js",
   "MemorySize": 128,
   "Role": "{{ tfstate `data.aws_iam_role.lambda.arn` }}",
-  "Runtime": "nodejs12.x",
+  "Runtime": "nodejs20.x",
   "Timeout": 5,
   "TracingConfig": {
     "Mode": "PassThrough"
@@ -508,6 +568,33 @@ data "aws_iam_role" "lambda" {
 }
 ```
 
+For Jsonnet, the `tfstate` native function is available.
+
+```jsonnet
+local tfstate = std.native('tfstate');
+{
+  Description: 'hello function',
+  FunctionName: 'hello',
+  Handler: 'index.js',
+  MemorySize: 128,
+  Role: tfstate('data.aws_iam_role.lambda.arn'),
+  Runtime: 'nodejs20.x',
+  Timeout: 5,
+  TracingConfig: {
+    Mode: 'PassThrough',
+  },
+  VpcConfig: {
+    SubnetIds: [
+      tfstate('aws_subnet.lambda["az-a"].id'),
+      tfstate('aws_subnet.lambda["az-b"].id'),
+    ],
+    SecurityGroupIds: [
+      tfstate('aws_security_group.internal["%s"].id' % must_env('WORLD')),
+    ],
+  },
+}
+```
+
 Likewise, if you have AWS resource definitions spread across multiple tfstate files, you can utilize `--prefixed-tfstate` option:
 
 e.g.
@@ -530,28 +617,23 @@ which then exposes additional template functions available like:
 }
 ```
 
-### Jsonnet support for function configuration
-
-lambroll also can read function.jsonnet as [Jsonnet](https://jsonnet.org/) format instead of plain JSON.
+For Jsonnet, a `{prefix}_tfstate` native function is generated by the `--prefixed-tfstate` option.
 
 ```jsonnet
+local first_tfstate = std.native('my_first_tfstate');
+local second_tfstate = std.native('my_second_tfstate');
 {
-  FunctionName: 'hello',
-  Handler: 'index.handler',
-  MemorySize: std.extVar('memorySize'),
-  Role: 'arn:aws:iam::%s:role/lambda_role' % [ std.extVar('accountID') ],
-  Runtime: 'nodejs20.x',
+  Description: 'hello function',
+  Environment: {
+    Variables: {
+      FIRST_VALUE: first_tfstate('data.aws_iam_role.lambda.arn'),
+      SECOND_VALUE: second_tfstate('data.aws_iam_role.lambda.arn'),
+    },
+  },
+  "rest of the parameters": "...",
 }
 ```
 
-```console
-$ lambroll \
-    --function function.jsonnet \
-    --ext-str accountID=0123456789012 \
-    --ext-code memorySize="128 * 4" \
-    deploy
-```
-
 ### .lambdaignore
 
 lambroll will ignore files defined in `.lambdaignore` file at creating a zip archive.