From 3ec1b8ff52341f62caff0b7cd3c9f35f910e34cd Mon Sep 17 00:00:00 2001
From: Jason Hall <jason@chainguard.dev>
Date: Mon, 11 Sep 2023 08:46:45 -0400
Subject: [PATCH] docs: add docs for TF and Lambda

Signed-off-by: Jason Hall <jason@chainguard.dev>
---
 docs/advanced/lambda.md    | 53 ++++++++++++++++++++++++++++++++++++++
 docs/advanced/terraform.md | 35 +++++++++++++++++++++++++
 2 files changed, 88 insertions(+)
 create mode 100644 docs/advanced/lambda.md
 create mode 100644 docs/advanced/terraform.md

diff --git a/docs/advanced/lambda.md b/docs/advanced/lambda.md
new file mode 100644
index 0000000000..ad1a4d478e
--- /dev/null
+++ b/docs/advanced/lambda.md
@@ -0,0 +1,53 @@
+# AWS Lambda
+
+`ko` can build images that can be deployed as AWS Lambda functions, using [Lambda's container support](https://docs.aws.amazon.com/lambda/latest/dg/images-create.html).
+
+For best results, use the [Go runtime interface client](https://docs.aws.amazon.com/lambda/latest/dg/go-image.html#go-image-clients) provided by the [`lambda` package](https://pkg.go.dev/github.com/aws/aws-lambda-go/lambda).
+
+For example:
+
+```go
+package main
+
+import (
+    "fmt"
+    "context"
+    "github.com/aws/aws-lambda-go/lambda"
+)
+
+type Event struct {
+    Name string `json:"name"`
+    // TODO: add other request fields here.
+}
+
+func main() {
+    lambda.Start(func(ctx context.Context, event Event) (string, error) {
+        return fmt.Sprintf("Hello %s!", event.Name), nil
+    }
+}
+```
+
+See AWS's [documentation](https://docs.aws.amazon.com/lambda/latest/dg/golang-handler.html) for more information on writing Lambda functions in Go.
+
+To deploy to Lambda, you must push to AWS Elastic Container Registry (ECR):
+
+```sh
+KO_DOCKER_REPO=[account-id].dkr.ecr.[region].amazonaws.com/my-repo
+image=$(ko build ./cmd/app)
+```
+
+Then, create a Lambda function using the image in ECR:
+
+```sh
+aws lambda create-function \
+  --function-name hello-world \
+  --package-type Image \
+  --code ImageUri=${image} \
+  --role arn:aws:iam::[account-id]:role/lambda-ex
+```
+
+See AWS's [documentation](https://docs.aws.amazon.com/lambda/latest/dg/go-image.html) for more information on deploying Lambda functions using Go container images, including how to configure push access to ECR, and how to configure the IAM role for the function.
+
+The base image that `ko` uses by default supports both x86 and Graviton2 architectures.
+
+You can also use the [`ko` Terraform provider](./terraform.md) to build and deploy Lambda functions as part of your IaC workflow, using the [`aws_lambda_function` resource](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lambda_function.html). See the [provider example](https://github.com/ko-build/terraform-provider-ko/tree/main/provider-examples/lambda) to get started.
diff --git a/docs/advanced/terraform.md b/docs/advanced/terraform.md
new file mode 100644
index 0000000000..4b2118f8b8
--- /dev/null
+++ b/docs/advanced/terraform.md
@@ -0,0 +1,35 @@
+# Terraform Provider
+
+In addition to the CLI, `ko`'s functionality is also available as a Terraform provider.
+
+This allows `ko` to be integrated with your Infrastructure-as-Code (IaC) workflows, and makes building your code a seamless part of your deployment process.
+
+Using the Terraform provider is as simple as adding a `ko_build` resource to your Terraform configuration:
+
+```hcl
+// Require the `ko-build/ko` provider.
+terraform {
+  required_providers {
+    ko = { source = "ko-build/ko" }
+  }
+}
+
+// Configure the provider to push to your repo.
+provider "ko" {
+  repo = "example.registry/my-repo" // equivalent to KO_DOCKER_REPO
+}
+
+// Build your code.
+resource "ko_build" "app" {
+  importpath = "github.com/example/repo/cmd/app"
+}
+
+// TODO: use the `ko_build.app` resource elsewhere in your Terraform configuration.
+
+// Report the build image's digest.
+output "image" {
+  value = ko_build.app.image
+}
+```
+
+See the [`ko-build/ko` provider on the Terraform Registry](https://registry.terraform.io/providers/ko-build/ko/latest) for more information, and the [GitHub repo](https://github.com/ko-build/terraform-provider-ko) for more examples.