feat(Geo) Construct: Phase 4 - Documentation

package.json

@@ -120,5 +120,5 @@
     "lint": "next lint",
     "clean-references": "node tasks/clean-references.mjs"
   },
-  "packageManager": "[email protected].0"
+  "packageManager": "[email protected].2"
 }

src/components/GeoLegacyResourcesBanner/GeoLegacyResourcesBanner.tsx

@@ -0,0 +1,28 @@
+import { Callout } from '@/components/Callout';
+import Link from 'next/link';
+import classNames from 'classnames';
+
+export const GeoLegacyResourcesBanner = () => {
+  return (
+    <Callout backgroundColor="background.error">
+      Amazon Location Service has introduced{' '}
+      <Link
+        href="https://us-west-2.console.aws.amazon.com/location/home?region=us-west-2#/feature-spotlight"
+        passHref
+        className={classNames('amplify-link')}
+      >
+        new APIs for Maps and Places
+      </Link>{' '}
+      which no longer require account-bound resources. Amplify Geo no longer
+      supports the provisioning of legacy (account-bound) maps and place
+      indices. Please{' '}
+      <Link
+        href="https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_location-readme.html"
+        passHref
+        className={classNames('amplify-link')}
+      >
+        visit the CDK API to learn more about provisioning legacy resources.
+      </Link>
+    </Callout>
+  );
+};

src/components/GeoLegacyResourcesBanner/index.ts

@@ -0,0 +1 @@
+export { GeoLegacyResourcesBanner } from './GeoLegacyResourcesBanner';

src/components/Layout/Layout.tsx

@@ -37,6 +37,7 @@ import {
 } from '@/components/NextPrevious';
 import { Modal } from '@/components/Modal';
 import { Gen1Banner } from '@/components/Gen1Banner';
+import { GeoLegacyResourcesBanner } from '../GeoLegacyResourcesBanner';
 import { PinpointEOLBanner } from '@/components/PinpointEOLBanner';
 import { LexV1EOLBanner } from '../LexV1EOLBanner';
 import { ApiModalProvider } from '../ApiDocs/ApiModalProvider';
@@ -288,6 +289,9 @@ export const Layout = ({
                     {(isGen1GettingStarted || isGen1HowAmplifyWorks) && (
                       <Gen1Banner currentPlatform={currentPlatform} />
                     )}
+                    {asPathWithNoHash.includes('/geo/set-up-geo/') && (
+                      <GeoLegacyResourcesBanner />
+                    )}
                     {(asPathWithNoHash.includes('/push-notifications/') ||
                       asPathWithNoHash.includes('/analytics/') ||
                       asPathWithNoHash.includes('/in-app-messaging/')) && (

src/directory/directory.mjs

@@ -396,6 +396,44 @@ export const directory = {
                 }
               ]
             },
+            {
+              path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/index.mdx',
+              children: [
+                {
+                  path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/set-up-geo/index.mdx'
+                },
+                {
+                  path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/custom-authorization/index.mdx'
+                },
+                {
+                  path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/maps/index.mdx'
+                },
+                {
+                  path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/configure-location-search/index.mdx'
+                },
+                {
+                  path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/location-search/index.mdx'
+                },
+                {
+                  path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/configure-geofencing/index.mdx'
+                },
+                {
+                  path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/geofences/index.mdx'
+                },
+                {
+                  path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/existing-resources/index.mdx'
+                },
+                {
+                  path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/use-legacy-resources/index.mdx'
+                },
+                {
+                  path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/google-migration/index.mdx'
+                },
+                {
+                  path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/amazon-location-sdk/index.mdx'
+                }
+              ]
+            },
             {
               path: 'src/pages/[platform]/build-a-backend/functions/index.mdx',
               children: [
@@ -524,38 +562,6 @@ export const directory = {
                     }
                   ]
                 },
-                {
-                  path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/index.mdx',
-                  children: [
-                    {
-                      path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/set-up-geo/index.mdx'
-                    },
-                    {
-                      path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/maps/index.mdx'
-                    },
-                    {
-                      path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/configure-location-search/index.mdx'
-                    },
-                    {
-                      path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/location-search/index.mdx'
-                    },
-                    {
-                      path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/configure-geofencing/index.mdx'
-                    },
-                    {
-                      path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/geofences/index.mdx'
-                    },
-                    {
-                      path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/existing-resources/index.mdx'
-                    },
-                    {
-                      path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/google-migration/index.mdx'
-                    },
-                    {
-                      path: 'src/pages/[platform]/build-a-backend/add-aws-services/geo/amazon-location-sdk/index.mdx'
-                    }
-                  ]
-                },
                 {
                   path: 'src/pages/[platform]/build-a-backend/add-aws-services/in-app-messaging/index.mdx',
                   children: [

src/pages/[platform]/build-a-backend/add-aws-services/geo/configure-geofencing/index.mdx

@@ -29,78 +29,70 @@ A Geofence is a virtual perimeter for a real-world geographic area. A Geofence c
 
 ## Setup a new Geofence Collection
 
+```ts title="amplify/geo/resource.ts"
+import { defineCollection } from "@aws-amplify/backend-geo";
+
+export const collection = defineCollection({
+  name: 'amplifyCollection',
+  description: 'This is an Amplify collection.',
+  access: (allow) => [
+    allow.authenticated.to(['create', 'read', 'update', 'delete', 'list']),
+    allow.guest.to(['read', 'list'])
+  ]
+});
+```
+
+Now update your `backend.ts` file with the collection created in your `resource.ts` file.
+
 ```ts title="amplify/backend.ts"
 import { defineBackend } from "@aws-amplify/backend";
 import { Policy, PolicyStatement } from "aws-cdk-lib/aws-iam";
 import { CfnGeofenceCollection } from "aws-cdk-lib/aws-location";
 import { auth } from "./auth/resource";
 import { data } from "./data/resource";
+import { collection } from "./geo/resource";
 
 const backend = defineBackend({
   auth,
   data,
-  // additional resources
+  collection
 });
+```
 
-const geoStack = backend.createStack("geo-stack");
-
-// create a location services geofence collection
-const myGeofenceCollection = new CfnGeofenceCollection(
-  geoStack,
-  "GeofenceCollection",
-  {
-    collectionName: "myGeofenceCollection",
-    pricingPlan: "RequestBasedUsage",
-    tags: [
-      {
-        key: "name",
-        value: "myGeofenceCollection",
-      },
-    ],
-  }
-);
-
-// create an IAM policy to allow interacting with geofence collection resource
-const myGeofenceCollectionPolicy = new Policy(
-  geoStack,
-  "GeofenceCollectionPolicy",
-  {
-    policyName: "myGeofenceCollectionPolicy",
-    statements: [
-      new PolicyStatement({
-        actions: [
-          "geo:GetGeofence",
-          "geo:PutGeofence",
-          "geo:BatchPutGeofence",
-          "geo:BatchDeleteGeofence",
-          "geo:ListGeofences",
-        ],
-        resources: [myGeofenceCollection.attrArn],
-      }),
-    ],
-  }
-);
-
-// apply the policy to the authenticated and unauthenticated roles
-backend.auth.resources.authenticatedUserIamRole.attachInlinePolicy(myGeofenceCollectionPolicy);
-backend.auth.resources.unauthenticatedUserIamRole.attachInlinePolicy(myGeofenceCollectionPolicy);
-
-// patch the geofence collection resource to the expected output configuration
-backend.addOutput({
-  geo: {
-    geofence_collections: {
-      default: myGeofenceCollection.collectionName,
-      items: [myGeofenceCollection.collectionName],
-    },
-  },
+<Callout warning="true">
+
+AWS Location API keys currently do not support geofence collections or their associated APIs. Adding access definitions for any API keys using the `allow.apiKey.to()` definition will NOT result in the creation of an API key.
+
+</Callout>
+
+## Configure additional geofence collections
+
+Amplify Geo gives you the ability to configure your backend to automatically request and manage multiple geofence collections.
+
+You can define these additional geofence collections by reusing the `defineCollection` function while providing a unique `name` to identify the collection. You can configure specific access permissions to these collections by adding them to the API with the unique `name`.
+
+<Callout info>
+
+**Note**: If numerous geofence collections are defined, then one of them must be marked as default using the `isDefault` flag.
+
+</Callout>
+
+```ts title="amplify/geo/resource.ts"
+export const firstCollection = defineCollection({
+  name: 'firstCollection',
+  isDefault: true
+});
+
+export const secondCollection = defineCollection({
+  name: 'secondCollection'
 });
 ```
 
 ## Geofence Collection Pricing Plan
 
 The pricing plan for the Geofence Collection will be set to `RequestBasedUsage`. We advice you to go through the [location service pricing](https://aws.amazon.com/location/pricing/) along with the [location service terms](https://aws.amazon.com/service-terms/) (_82.5 section_) to learn more about the pricing plan.
 
-#### Group access
+### Group access
 
 To scope access permissions based on [Cognito User Groups](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-user-groups.html)
 
@@ -117,30 +109,21 @@ export const auth = defineAuth({
 });
 ```
 
-2. Add permissions to the Cognito User Pool Group role
+2. Update the collection access definition in your `resource.ts`
 
-```ts title="amplify/backend.ts"
-const myGeofenceCollectionPolicy = new Policy(
-  geoStack,
-  "GeofenceCollectionPolicy",
-  {
-    policyName: "myGeofenceCollectionPolicy",
-    statements: [
-      new PolicyStatement({
-        actions: [
-          "geo:GetGeofence",
-          "geo:PutGeofence",
-          "geo:BatchPutGeofence",
-          "geo:BatchDeleteGeofence",
-          "geo:ListGeofences",
-        ],
-        resources: [myGeofenceCollection.attrArn],
-      }),
-    ],
-  }
-);
-
-backend.auth.resources.groups["User"].role.attachInlinePolicy(myGeofenceCollectionPolicy);
+```ts title="amplify/geo/resource.ts"
+import { defineCollection } from "@aws-amplify/backend-geo";
+
+export const collection = defineCollection({
+  name: 'amplifyCollection',
+  description: 'This is an Amplify collection.',
+  access: (allow) => [
+    allow.authenticated.to(['create', 'read', 'update', 'delete', 'list']),
+    allow.guest.to(['read', 'list']),
+    // highlight-next-line
+    allow.groups("User").to(['read', 'update'])
+  ]
+});
 ```
 
 > Note: If you combine `Auth/Guest user access` and `Individual Group access`, users who are members of a group will only be granted the permissions of the group, and not the authenticated user permissions. The permissions apply to ALL Geofences in a collection. For example, If you add `Read` permission such as `ListGeofences` and `GetGeofence` to `User` Cognito group, ALL users added to that group will be able to read the properties of ALL Geofences in that Geofence collection.