From c8dafe724972ae3e441aaf3113fe5baf21d4e24c Mon Sep 17 00:00:00 2001 From: Pedro Arantes Date: Sat, 24 Oct 2020 11:03:29 -0300 Subject: [PATCH] feat: adding lambda layer documentation --- packages/cli/src/deploy/cloudFormation.ts | 4 +- packages/cli/src/deploy/lambdaLayer.ts | 8 ++ packages/website/api/commands.ts | 1 + packages/website/api/getComments.ts | 9 -- packages/website/api/getTemplates.ts | 2 - packages/website/api/vars.ts | 5 +- packages/website/components/Layout.tsx | 4 + .../pages/docs/usage/deploy-lambda-layer.tsx | 98 +++++++++++++++++++ .../pages/docs/usage/deploy-static-app.tsx | 13 +-- 9 files changed, 125 insertions(+), 19 deletions(-) create mode 100644 packages/website/pages/docs/usage/deploy-lambda-layer.tsx diff --git a/packages/cli/src/deploy/cloudFormation.ts b/packages/cli/src/deploy/cloudFormation.ts index 76f76cc..48500b8 100644 --- a/packages/cli/src/deploy/cloudFormation.ts +++ b/packages/cli/src/deploy/cloudFormation.ts @@ -19,7 +19,9 @@ const logPrefix = 'cloudformation'; log.addLevel('event', 10000, { fg: 'yellow' }); log.addLevel('output', 10000, { fg: 'blue' }); -// https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html +/** + * https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html + */ const TEMPLATE_BODY_MAX_SIZE = 51200; const isTemplateBodyGreaterThanMaxSize = ( diff --git a/packages/cli/src/deploy/lambdaLayer.ts b/packages/cli/src/deploy/lambdaLayer.ts index 410c292..00c8e71 100644 --- a/packages/cli/src/deploy/lambdaLayer.ts +++ b/packages/cli/src/deploy/lambdaLayer.ts @@ -29,6 +29,14 @@ export const getZipNodeModules = async () => { return zip.toBuffer(); }; +/** + * The CloudFormation template created to deploy a Lambda Layer. + * + * - The Description fields of the Output and the LambdaLayer resource use the + * name and version of the package.json dependencies and is limited to a limit + * defined by: {@link https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-layerversion.html#cfn-lambda-layerversion-description} + * - The Layer name is the same as the Stack name. + */ export const getLambdaLayerTemplate = (): CloudFormationTemplate => { const { dependencies } = (() => { try { diff --git a/packages/website/api/commands.ts b/packages/website/api/commands.ts index b32b5af..342f4c4 100644 --- a/packages/website/api/commands.ts +++ b/packages/website/api/commands.ts @@ -3,4 +3,5 @@ export const commands = [ 'deploy', 'deploy base-stack', 'deploy static-app', + 'deploy lambda-layer', ]; diff --git a/packages/website/api/getComments.ts b/packages/website/api/getComments.ts index c7ac9eb..ee0774b 100644 --- a/packages/website/api/getComments.ts +++ b/packages/website/api/getComments.ts @@ -29,12 +29,3 @@ export const getComments = >( }; }, {} as any); }; - -export const tt = () => - jsdoc.explainSync({ - files: path.resolve( - process.cwd(), - '../cli/dist', - 'deploy/staticApp/staticApp.template.js', - ), - }); diff --git a/packages/website/api/getTemplates.ts b/packages/website/api/getTemplates.ts index 739135b..eb8bd15 100644 --- a/packages/website/api/getTemplates.ts +++ b/packages/website/api/getTemplates.ts @@ -1,8 +1,6 @@ import { dumpToYamlCloudFormationTemplate } from 'carlin/dist/utils'; import { CloudFormationTemplate } from 'carlin/dist/utils/cloudFormationTemplate'; -export { getStaticAppTemplate } from 'carlin/dist/deploy/staticApp/staticApp.template'; - export type JsonYamlTemplates = { templateJson: any; templateYaml: string; diff --git a/packages/website/api/vars.ts b/packages/website/api/vars.ts index bf6d04c..a43dc83 100644 --- a/packages/website/api/vars.ts +++ b/packages/website/api/vars.ts @@ -1,4 +1,7 @@ +export { getLambdaLayerTemplate } from 'carlin/dist/deploy/lambdaLayer'; + export { - originCacheExpression, getLambdaEdgeOriginResponseZipFile, + getStaticAppTemplate, + originCacheExpression, } from 'carlin/dist/deploy/staticApp/staticApp.template'; diff --git a/packages/website/components/Layout.tsx b/packages/website/components/Layout.tsx index 15bc95c..66219f2 100644 --- a/packages/website/components/Layout.tsx +++ b/packages/website/components/Layout.tsx @@ -38,6 +38,10 @@ const navs: Array<{ name: 'deploy static-app', href: '/docs/usage/deploy-static-app', }, + { + name: 'deploy lambda-layer', + href: '/docs/usage/deploy-lambda-layer', + }, ], }, { diff --git a/packages/website/pages/docs/usage/deploy-lambda-layer.tsx b/packages/website/pages/docs/usage/deploy-lambda-layer.tsx new file mode 100644 index 0000000..9284848 --- /dev/null +++ b/packages/website/pages/docs/usage/deploy-lambda-layer.tsx @@ -0,0 +1,98 @@ +import { Styled } from 'theme-ui'; + +import { getComments } from '../../../api/getComments'; +import { getJsonYamlTemplates } from '../../../api/getTemplates'; +import { getLambdaLayerTemplate } from '../../../api/vars'; + +import CodeBlock from '../../../components/CodeBlock'; + +export const getStaticProps = async () => { + const root = { + comments: getComments({ + deployLambdaLayer: 'deploy/lambdaLayer.js', + getLambdaLayerTemplate: 'deploy/lambdaLayer.js', + }), + }; + + const lambdaLayerTemplateYaml = getJsonYamlTemplates(getLambdaLayerTemplate()) + .templateYaml; + + return { props: { root, lambdaLayerTemplateYaml } }; +}; + +type ThenArg = T extends PromiseLike ? U : T; + +type Props = ThenArg>['props']; + +const DocsUsageDeployStaticApp = ({ root, lambdaLayerTemplateYaml }: Props) => { + return ( +
+ deploy lambda-layer +
+ carlin deploy lambda-layer + + When you execute + deploy lambda-layer + , these steps are performed: + + {root.comments.deployLambdaLayer} +
+
+ + The CloudFormation template created (in this example, + Description + + fields were created using the dependencies of this website): + + + + {root.comments.getLambdaLayerTemplate} + + {lambdaLayerTemplateYaml} +
+ {/* Usage +
+ Only S3 Bucket + + This deploy creates a single bucket to host de static files. The + template created is shown below: + + {onlyS3.template.templateYaml} +
+
+ CloudFront + + Besides creating a S3 bucket, this deploy also add CloudFront to + deployment. Lambda@Edge is used together with CloudFront whose + functionality is explained below: + + + {[ + cloudfront.comments.getLambdaEdgeOriginResponseZipFile, + '\n', + cloudfront.comments.originCacheExpression, + `const originCacheExpression = '${cloudfront.originCacheExpression}';`, + ].join('\n')} + + The Lambda@Edge code is show below: + + {cloudfront.getLambdaEdgeOriginResponseZipFile} + + + The Lambda@Edge code with custom SCP + {cloudfront.customScp} + is show below: + + + {cloudfront.getLambdaEdgeOriginResponseZipFileWithScp} + + The CloudFormation template created is shown below: + + {cloudfront.template.templateYaml} + */} + {/*
*/} +
+ ); +}; + +export default DocsUsageDeployStaticApp; diff --git a/packages/website/pages/docs/usage/deploy-static-app.tsx b/packages/website/pages/docs/usage/deploy-static-app.tsx index 829a6ff..f07b2f9 100644 --- a/packages/website/pages/docs/usage/deploy-static-app.tsx +++ b/packages/website/pages/docs/usage/deploy-static-app.tsx @@ -1,10 +1,7 @@ import { Styled } from 'theme-ui'; import { getComments } from '../../../api/getComments'; -import { - getJsonYamlTemplates, - getStaticAppTemplate, -} from '../../../api/getTemplates'; +import { getJsonYamlTemplates } from '../../../api/getTemplates'; import * as apiVars from '../../../api/vars'; import CodeBlock from '../../../components/CodeBlock'; @@ -18,13 +15,17 @@ export const getStaticProps = async () => { const onlyS3 = (() => { const options = { cloudfront: false, spa: false }; - const template = getJsonYamlTemplates(getStaticAppTemplate(options)); + const template = getJsonYamlTemplates( + apiVars.getStaticAppTemplate(options), + ); return { options, template }; })(); const cloudfront = (() => { const options = { cloudfront: true, spa: false }; - const template = getJsonYamlTemplates(getStaticAppTemplate(options)); + const template = getJsonYamlTemplates( + apiVars.getStaticAppTemplate(options), + ); const comments = getComments({ getLambdaEdgeOriginResponseZipFile: 'deploy/staticApp/staticApp.template.js',