Merge branch 'next-release/main' into renbran/setup-data-gen-2-android-swift

Author: renebrandel

public/images/storing-db-creds-in-secrets-manager.png

@@ -229,7 +229,7 @@ export const directory = {
               path: 'src/pages/[platform]/build-a-backend/functions/index.mdx',
               children: [
                 {
-                  path: 'src/pages/[platform]/build-a-backend/functions/set-up-function/index.mdx'
+                  path: 'src/pages/[platform]/build-a-backend/functions/define-function/index.mdx'
                 },
                 {
                   path: 'src/pages/[platform]/build-a-backend/functions/environment-variables-and-secrets/index.mdx'

src/directory/directory.mjs

@@ -92,7 +92,7 @@ Amplify.configure({
     identityPoolId: 'us-east-1:xxx-xxx-xxx-xxx-xxx',
     region: 'us-east-1'
   },
-  predictions: {
+  Predictions: {
     convert: {
       translateText: {
         region: 'us-east-1',

src/fragments/lib/predictions/js/getting-started.mdx

@@ -1,7 +1,7 @@
 import { getCustomStaticPath } from '@/utils/getCustomStaticPath';
 
 export const meta = {
-  title: 'Set up an Amplify Function',
+  title: 'Define an Amplify Function',
   description:
     'Use AWS Lambda functions to perform tasks and customize workflows.',
   platforms: [
@@ -29,44 +29,49 @@ export function getStaticProps(context) {
   };
 }
 
-Amplify Functions are powered by [AWS Lambda](https://aws.amazon.com/lambda/), and allow you to perform a wide variety of customization through contained _functions_.
+Amplify Functions are powered by [AWS Lambda](https://aws.amazon.com/lambda/), and allow you to perform a wide variety of customization through self-contained _functions_. Functions can respond to events from other resources, execute some logic in-between events like an authentication flow, or act as standalone jobs. They are used in a variety of settings and use cases:
+
+- Authentication flow customizations (e.g. attribute validations, allowlisting email domains)
+- Resolvers for GraphQL APIs
+- Handlers for individual REST API routes, or to host an entire API
+- Scheduled jobs
 
 ## Define a Function
 
-To get started, create a new directory and a resource file, `amplify/functions/my-demo-function/resource.ts`. Then, define the Function with `defineFunction`:
+To get started, create a new directory and a resource file, `amplify/functions/say-hello/resource.ts`. Then, define the Function with `defineFunction`:
 
-```ts title="amplify/functions/my-demo-function/resource.ts"
+```ts title="amplify/functions/say-hello/resource.ts"
 import { defineFunction } from '@aws-amplify/backend';
 
-export const myDemoFunction = defineFunction({
+export const sayHello = defineFunction({
   // optionally specify a name for the Function (defaults to directory name)
-  name: 'my-demo-function',
+  name: 'say-hello',
   // optionally specify a path to your handler (defaults to "./handler.ts")
   entry: './handler.ts'
 });
 ```
 
-Next, create the corresponding handler file at `amplify/functions/my-demo-function/handler.ts`. This is where your function code will go.
+Next, create the corresponding handler file at `amplify/functions/say-hello/handler.ts`. This is where your function code will go.
 
-```ts title="amplify/functions/my-demo-function/handler.ts"
+```ts title="amplify/functions/say-hello/handler.ts"
 export const handler = async (event) => {
   // your function code goes here
-  return 'You made a function!';
+  return 'Hello, World!';
 };
 ```
 
-The handler file _must_ export an async function named "handler". This is the entry point to your function. For more information on writing functions, refer to the [AWS documentation for Lambda function handlers using Node.js](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html).
+The handler file _must_ export a function named "handler". This is the entry point to your function. For more information on writing functions, refer to the [AWS documentation for Lambda function handlers using Node.js](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html).
 
 Lastly, this function needs to be added to your backend.
 
 ```ts title="amplify/backend.ts"
 import { defineBackend } from '@aws-amplify/backend';
 // highlight-next-line
-import { myDemoFunction } from './functions/my-demo-function/resource';
+import { sayHello } from './functions/say-hello/resource';
 
 defineBackend({
   // highlight-next-line
-  myDemoFunction
+  sayHello
 });
 ```
 
@@ -76,7 +81,7 @@ Now when you run `npx amplify sandbox` or deploy your app on Amplify, it will in
 
 Now that you have completed setting up your first Function, you may also want to add some additional features or modify a few settings. We recommend you learn more about:
 
-- [Environment variables and secrets](../environment-variables-and-secrets/)
-- [Grant access to other resources](../grant-access-to-other-resources/)
-- [Explore example use cases](../examples/)
-- [Modifying underlying resources with CDK](../modify-resources-with-cdk/)
+- [Environment variables and secrets](/[platform]/build-a-backend/functions/environment-variables-and-secrets/)
+- [Grant access to other resources](/[platform]/build-a-backend/functions/grant-access-to-other-resources/)
+- [Explore example use cases](/[platform]/build-a-backend/functions/examples/)
+- [Modifying underlying resources with CDK](/[platform]/build-a-backend/functions/modify-resources-with-cdk/)

src/pages/[platform]/build-a-backend/functions/set-up-function/index.mdx renamed to src/pages/[platform]/build-a-backend/functions/define-function/index.mdx

@@ -29,7 +29,7 @@ export function getStaticProps() {
   };
 }
 
-Amplify Gen 2 Functions support setting environment variables and secrets on the `environment` property of `defineFunction`.
+Amplify Functions support setting environment variables and secrets on the `environment` property of `defineFunction`.
 
 <Callout warning>
 
@@ -41,25 +41,26 @@ Amplify Gen 2 Functions support setting environment variables and secrets on the
 
 Environment variables can be configured in `defineFunction` using the `environment` property.
 
-```ts title="amplify/functions/my-demo-function/resource.ts"
+```ts title="amplify/functions/say-hello/resource.ts"
 import { defineFunction } from '@aws-amplify/backend';
 
-export const myDemoFunction = defineFunction({
+export const sayHello = defineFunction({
   environment: {
-    ENV_VAR_NAME: 'someValueHere'
+    NAME: 'World'
   }
 });
 ```
 
 Any environment variables specified here will be available to the function at runtime.
 
-Some environment variables are constant across all branches and deployments. But many environment values differ between deployment environments. [Branch-specific environment variables can be configured for Amplify hosting deployments](/gen2/deploy-and-host/fullstack-branching/secrets-and-vars/#set-environment-variables).
+Some environment variables are constant across all branches and deployments. But many environment values differ between deployment environments. [Branch-specific environment variables can be configured for Amplify hosting deployments](/[platform]/deploy-and-host/fullstack-branching/secrets-and-vars/).
 
 Suppose you created a branch-specific environment variable in hosting called "API_ENDPOINT" which had a different value for your "staging" vs "prod" branch. If you wanted that value to be available to your function you can pass it to the function using
 
-```ts title="amplify/functions/my-demo-function/resource.ts"
-export const myDemoFunction = defineFunction({
+```ts title="amplify/functions/say-hello/resource.ts"
+export const sayHello = defineFunction({
   environment: {
+    NAME: "World",
     API_ENDPOINT: process.env.API_ENDPOINT
   }
 });
@@ -69,13 +70,13 @@ export const myDemoFunction = defineFunction({
 
 Within your function handler, you can access environment variables using the normal `process.env` global object provided by the Node runtime. However, this does not make it easy to discover what environment variables will be available at runtime. Amplify generates an `env` symbol that can be used in your function handler and provides typings for all variables that will be available at runtime. Copy the following code to use it.
 
-```ts title="amplify/functions/my-demo-function/handler.ts"
+```ts title="amplify/functions/say-hello/handler.ts"
 // highlight-next-line
-import { env } from '$amplify/env/my-demo-function'; // the import is '$amplify/env/<function name>'
+import { env } from '$amplify/env/say-hello'; // the import is '$amplify/env/<function name>'
 
 export const handler = async (event) => {
-  env. // the env object has intellisense for all environment variables that are available to the function
-  return 'You made a function!';
+  // the env object has intellisense for all environment variables that are available to the function
+  return `Hello, ${env.NAME}!`;
 };
 ```
 
@@ -103,25 +104,33 @@ If you did not, you will need to manually configure your project. Within your `a
 
 Sometimes it is necessary to provide a secret value to a function. For example, it may need a database password or an API key to perform some business use case. Environment variables should NOT be used for this because environment variable values are included in plaintext in the function configuration. Instead, secret access can be used.
 
-Before using a secret in a function, you need to [define a secret](/gen2/deploy-and-host/fullstack-branching/secrets-and-vars/#set-secrets). After you have defined a secret, you can reference it in your function config.
+Before using a secret in a function, you need to [define a secret](/[platform]/deploy-and-host/fullstack-branching/secrets-and-vars/#set-secrets). After you have defined a secret, you can reference it in your function config.
 
-```ts title="amplify/functions/my-demo-function/resource.ts"
+```ts title="amplify/functions/say-hello/resource.ts"
 import { defineFunction, secret } from '@aws-amplify/backend';
 
-export const myDemoFunction = defineFunction({
+export const sayHello = defineFunction({
   environment: {
-    API_KEY: secret('myApiKey') // this assumes you created a secret named "myApiKey"
+    NAME: "World",
+    API_ENDPOINT: process.env.API_ENDPOINT,
+    API_KEY: secret('MY_API_KEY') // this assumes you created a secret named "MY_API_KEY"
   }
 });
 ```
 
 You can use this secret value at runtime in your function the same as any other environment variable. However, you will notice that the value of the environment variable is not stored as part of the function configuration. Instead, the value is fetched when your function runs and is provided in memory.
 
-```ts title="amplify/functions/my-demo-function/handler.ts"
-import { env } from '$amplify/env/my-demo-function';
+```ts title="amplify/functions/say-hello/handler.ts"
+import { env } from '$amplify/env/say-hello';
 
 export const handler = async (event) => {
-  env.API_KEY; // this is the value of secret named "myApiKey"
-  return 'You made a function!';
+  const request = new Request(env.API_ENDPOINT, {
+    headers: {
+      // this is the value of secret named "MY_API_KEY"
+      Authorization: `Bearer ${env.API_KEY}`
+    }
+  })
+  // ...
+  return `Hello, ${env.NAME}!`;
 };
 ```

src/pages/[platform]/build-a-backend/functions/environment-variables-and-secrets/index.mdx

@@ -29,17 +29,33 @@ export function getStaticProps() {
   };
 }
 
-When you grant a function access to another resource in your Amplify backend ([such as granting access to storage](/[platform]/build-a-backend/storage/#resource-access)), that will configure environment variables for that function to make SDK calls to the AWS services it has access to. Those environment variables are typed and available as part of the `env` object.
+In order for Amplify Functions to interact with other resources they must be given access. There are two ways to grant Amplify Functions access to other resources:
 
-Example `defineStorage` that grants myDemoFunction access to files in `/foo/*`.
+1. [Using the `access` property](#using-the-access-property)
+2. [Using the AWS Cloud Development Kit (CDK)](#using-cdk)
+
+## Using the `access` property
+
+The `access` property is a property found in each of the `define*` functions for defining Amplify resources. It allows you specify the necessary actions using common language.
+
+<Callout>
+
+When you grant a function access to another resource in your Amplify backend ([such as granting access to storage](/[platform]/build-a-backend/storage/#resource-access)), it will configure environment variables for that function to make SDK calls to the AWS services it has access to. Those environment variables are typed and available as part of the `env` object.
+
+</Callout>
+
+Say you have a function that generates reports each month from your Data resource and needs to store the generated reports in Storage:
 
 ```ts title="amplify/storage/resource.ts"
-import { myDemoFunction } from '../functions/my-demo-function/resource';
+import { defineStorage } from '@aws-amplify/backend';
+import { generateMonthlyReports } from '../functions/generate-monthly-reports/resource';
 
 export const storage = defineStorage({
-  name: 'myProjectFiles',
+  name: 'myReports',
   access: (allow) => ({
-    '/foo/*': [allow.resource(demoFunction).to(['read', 'write', 'delete'])]
+    '/reports/*': [
+      allow.resource(generateMonthlyReports).to(['read', 'write', 'delete'])
+    ]
   })
 });
 ```
@@ -48,19 +64,76 @@ This access definition will add the environment variable `myProjectFiles_BUCKET_
 
 Here's an example of how it can be used to upload some content to S3.
 
-```ts title="amplify/functions/my-demo-function/handler.ts"
-import { env } from '$amplify/env/my-demo-function';
+```ts title="amplify/functions/generate-monthly-reports/handler.ts"
 import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { env } from '$amplify/env/generate-monthly-reports';
 
 const s3Client = new S3Client();
 
-export const handler = async (event) => {
-  await s3Client.send(
-    new PutObjectCommand({
-      Bucket: env.myProjectFiles_BUCKET_NAME,
-      Key: 'foo/someFile.txt',
-      Body: 'this is an example'
-    })
-  );
+export const handler = async () => {
+  const command = new PutObjectCommand({
+    Bucket: env.myReports_BUCKET_NAME,
+    Key: `reports/${new Date().toISOString()}.csv`,
+    Body: new Blob([''], { type: 'text/csv;charset=utf-8;' })
+  });
+
+  await s3Client.send(command);
 };
 ```
+
+## Using CDK
+
+When permissions are needed to access resources beyond the capabilities of the `access` property, you must use CDK.
+
+Functions are created with an [_execution role_](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html), which is an IAM role that contains policies that dictate what resources your Function can interact with when it executes. This role can be extended using the [`addToRolePolicy()`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.IFunction.html#addwbrtowbrrolewbrpolicystatement) method:
+
+```ts title="amplify/backend.ts"
+import { defineBackend } from "@aws-amplify/backend"
+import * as iam from "aws-cdk-lib/aws-iam"
+import * as sns from "aws-cdk-lib/aws-sns"
+import { weeklyDigest } from "./functions/weekly-digest/resource"
+
+const backend = defineBackend({
+  weeklyDigest,
+})
+
+const weeklyDigestLambda = backend.weeklyDigest.resources.lambda
+
+const topicStack = backend.createStack("WeeklyDigest")
+const topic = new sns.Topic(topicStack, "Topic", {
+  displayName: "digest",
+})
+
+// highlight-start
+const statement = new iam.PolicyStatement({
+  sid: "AllowPublishToDigest",
+  actions: ["sns:Publish"],
+  resources: [topic.topicArn],
+})
+
+weeklyDigestLambda.addToRolePolicy(statement)
+  // highlight-end
+```
+
+However some constructs provide a `grant*` method to grant access to common policy actions. Revisiting the example above you can grant the same access with `grantPublish`:
+
+```ts title="amplify/backend.ts"
+import { defineBackend } from "@aws-amplify/backend"
+import * as iam from "aws-cdk-lib/aws-iam"
+import * as sns from "aws-cdk-lib/aws-sns"
+import { weeklyDigest } from "./functions/weekly-digest/resource"
+
+const backend = defineBackend({
+  weeklyDigest,
+})
+
+const weeklyDigestLambda = backend.weeklyDigest.resources.lambda
+
+const topicStack = backend.createStack("WeeklyDigest")
+const topic = new sns.Topic(topicStack, "Topic", {
+  displayName: "digest"
+})
+
+// highlight-next-line
+topic.grantPublish(weeklyDigestLambda)
+```

src/pages/[platform]/build-a-backend/functions/grant-access-to-other-resources/index.mdx

@@ -35,7 +35,7 @@ export function getStaticProps() {
 
 <Callout warning>
 
-**Under active development:** The Functions experience for Amplify Gen 2 is under active development. The experience may change between versions of `@aws-amplify/backend`. Try it out and provide feedback at https://github.com/aws-amplify/amplify-backend/issues/new/choose
+**Under active development:** The Functions experience for Amplify is under active development. The experience may change between versions of `@aws-amplify/backend`. Try it out and provide feedback at https://github.com/aws-amplify/amplify-backend/issues/new/choose
 
 </Callout>
 

src/pages/[platform]/build-a-backend/functions/index.mdx

@@ -29,6 +29,27 @@ export function getStaticProps(context) {
   };
 }
 
+Amplify Functions utilize the [`NodejsFunction`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.NodejsFunction.html) construct from the [AWS Cloud Development Kit (CDK)](https://aws.amazon.com/cdk/). The underlying resources can be modified, overridden, or extended using CDK after setting the resource on your backend.
+
+```ts title="amplify/backend.ts"
+import { defineBackend } from '@aws-amplify/backend';
+import { myFunction } from './functions/my-function';
+
+const backend = defineBackend({
+  myFunction
+})
+
+// CDK constructs can be accessed via
+backend.myFunction.resources
+
+// where the Lambda function can be found on
+backend.myFunction.resources.lambda
+```
+
+The Lambda resource available is a representation of [`IFunction`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.IFunction.html). 
+
 ## Adding IAM Policies
 
+To learn how to add IAM policies to a Function's execution role, visit the [documentation for granting access to other resources](/[platform]/build-a-backend/functions/grant-access-to-other-resources#using-cdk).
+
 {/* ## Lambda Layers */}