From 683a61eb7bf10503601e2febddcf0a56d1ecb266 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Fri, 30 Nov 2018 11:49:05 -0800 Subject: [PATCH 01/20] Add sam publish app design doc --- designs/sam_publish_app_cmd.rst | 229 ++++++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 designs/sam_publish_app_cmd.rst diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst new file mode 100644 index 0000000000..0c1abe632d --- /dev/null +++ b/designs/sam_publish_app_cmd.rst @@ -0,0 +1,229 @@ +.. contents:: **Table of Contents** + :depth: 2 + :local: + +``sam publish app`` command +==================================== + +This is the design for a command to publish an application to `AWS Serverless Application Repository (SAR)`_ with a SAM +template. It can be used to create a new application and its first version, update exisitng application's metadata, create +a new version of the application, and manage application permissions. + +.. _AWS Serverless Application Repository (SAR): https://aws.amazon.com/serverless/serverlessrepo/ + + +What is the problem? +-------------------- +To publish an app to AWS Serverless Application Repository, customers need to go through the following steps: first upload +the application code and SAM template to an Amazon S3 bucket, correctly set S3 bucket policy that grants the service read +permissions for artifacts uploaded to S3, then open the AWS Serverless Application Repository console and provide information +in a bunch of input boxes. If they use the AWS CLI, they need to pass all the information as parameters, and it's easy to make +a mistake while typing in the command line. + + +What will be changed? +--------------------- +In this proposal, we will be providing a new command, ``sam publish app``, which takes a SAM template as input and publishes +an application to AWS Serverless Application Repository using applicaiton metadata specified in the template. Customers just +need to provide application metadata information in the template, then ``sam publish app`` will handle uploading local files +to S3 and creating the app. We will also provde sharing options to set application permission policies. This command will +greatly simplify the exsiting publishing experience. + + +Success criteria for the change +------------------------------- +#. Support all the following use cases: + + * Create new application and its first version in SAR using ``sam publish app`` + * Update existing SAR application (metadata only) using ``sam publish app --meta-data`` + * Create new version of existing SAR application using ``sam publish app`` + * Share the app publicly using the ``--make-public`` option + * Make the app private using the ``--make-private`` option + * Share the app privately with other AWS accounts using the ``--account-ids`` option + + +#. ``sam package`` command can upload local readme/license files to S3. + +#. sample app template generated by ``sam init`` will include the "AWS::ServerlessRepo::Application" section. + + +Out-of-Scope +------------ +#. Create new application or version if the ``--meta-data`` option is used. + +#. Manage application permission separately without publishing/updating the app. + +#. Specify type of `application permission`_ in sharing options. + +#. Recursively publish nested apps in the template. + +#. Run through CI/CD pipeline for the application before publishing. + +#. Support downloading an app to edite/republish it. + +#. Publish to other repositories besides SAR. + +#. Recognize template changes and suggest version number. + +#. Parse metadata from template without an AWS::ServerlessRepo::Application section. + +.. _application permission: https://docs.aws.amazon.com/serverlessrepo/latest/devguide/access-control-resource-based.html#application-permissions + + +User Experience Walkthrough +--------------------------- + +Assuming that customers have the following SAM template: + +.. code-block:: yaml + + Metadata: + AWS::ServerlessRepo::Application: + Name: my-app + Description: hello world + Author: user1 + SpdxLicenseId: Apache-2.0 + LicenseUrl: ./LICENSE.txt + ReadmeUrl: ./README.md + Labels: ['tests'] + HomepageUrl: https://github.com/user1/my-app-project + SemanticVersion: 1.0.0 + SourceCodeUrl: https://github.com/user1/my-app-project + + Resources: + HelloWorldFunction: + Type: AWS::Lambda::Function + Properties: + CodeUri: s3://bucket/hello-world + +Package SAM template + Run ``sam package --template-file ./template.yaml --output-template-file packaged.yaml --s3-bucket my-bucket`` + to upload code artifacts, readme and license files to S3 and generate the packaged template. + +Create new application in SAR + Run ``sam publish app -t ./packaged.yaml`` to publish a new application named my-app in SAR with the first version + created as 1.0.0. The app will be created as private by default. + +Create new version of an existing SAR application + Modify the existing template, give a different SemanticVersion value, and run ``sam publish app -t ./packaged.yaml``. + +Crete application/version and set application permission + Run ``sam publish app -t ./packaged.yaml --make-public`` to publish the app and share it publicly. If ``--make-private`` + option is used, the app will only be visible to the owner. If ``--account-ids `` is used, the app will be + shared with the provided AWS accounts. + +Update the metadata of an exsiting application + Run ``sam publish app -t ./packaged.yaml --meta-data --application-id `` to update the application metadata. + Only changes to Description, Author, ReadmeUrl, Labels, and HomepageUrl will be honored because other fields are not + allowed to modify or are version specific. + +Output of the ``sam publish app`` command will be a link to the AWS Serverless Application Repository console details page +of the app just published. + +Implementation +============== + +CLI Changes +----------- +*Explain the changes to command line interface, including adding new commands, modifying arguments etc* + +1. Add a new top-level command called ``sam publish app`` with the following options. + + -t, --template PATH AWS SAM template to publish. + --region TEXT Set the AWS Region of the service (e.g. us-east-1). + --application-id TEXT Specify the application id to update. + --meta-data Update the application metadata. + --make-public Share the app publicly with anyone. + --make-private Share the app only with the owning account. + --account-ids TEXT Share the app privately with the given comma-separated list + of AWS account ids. + --profile TEXT Select a specific profile from your credential file to + get AWS credentials. + --debug Turn on debug logging to print debug message generated + by SAM CLI. + --help Show this message and exit. + +2. Update ``sam package`` command to support uploading locally referenced readme and license files to S3. + +3. Update ``sam init`` command to support generating AWS::ServerlessRepo::Application section in the sample app template. + +Breaking Change +~~~~~~~~~~~~~~~ +*Are there any breaking changes to CLI interface? Explain* + +N/A + +Design +------ +*Explain how this feature will be implemented. Highlight the components of your implementation, relationships* +*between components, constraints, etc.* + +SAM CLI will read the packaged SAM template and pass it as string to `aws-serverlessrepo-python `_ +library. The algorithm for ``sam publish app -t ./packaged.yaml --make-public`` looks like this: + +.. code-block:: python + + from serverlessrepo import publish_application, make_application_public + + with open('./packaged.yaml', 'r') as f: + template = f.read() + result = publish_application(template) + make_application_public(result.applicaiton_id) + + +``.samrc`` Changes +------------------ +*Explain the new configuration entries, if any, you want to add to .samrc* + +N/A + +Security +-------- + +*Tip: How does this change impact security? Answer the following questions to help answer this question better:* + +**What new dependencies (libraries/cli) does this change require?** + +A new dependency `aws-serverlessrepo-python `_ will be added to interact with SAR. + +**What other Docker container images are you using?** + +N/A + +**Are you creating a new HTTP endpoint? If so explain how it will be created & used** + +N/A + +**Are you connecting to a remote API? If so explain how is this connection secured** + +N/A + +**Are you reading/writing to a temporary folder? If so, what is this used for and when do you clean up?** + +N/A + +**How do you validate new .samrc configuration?** + +N/A + +Documentation Changes +--------------------- + +We will document how to use the new ``sam publish app`` command for publishing SAR applications, and link to +the "AWS::ServerlessRepo::Application" sepc in CloudFormation documentation. + +Open Issues +----------- + +N/A + +Task Breakdown +-------------- +- [x] Send a Pull Request with this design document +- [ ] Build the command line interface +- [ ] Build the underlying library +- [ ] Unit tests +- [ ] Functional Tests +- [ ] Integration tests +- [ ] Run all tests on Windows +- [ ] Update documentation From a1bfa611777bae2a1fa86ddd0ddcc5e5a34cc646 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Tue, 4 Dec 2018 15:27:43 -0800 Subject: [PATCH 02/20] Address comments --- designs/sam_publish_app_cmd.rst | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index 0c1abe632d..1246828c23 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -26,7 +26,7 @@ What will be changed? In this proposal, we will be providing a new command, ``sam publish app``, which takes a SAM template as input and publishes an application to AWS Serverless Application Repository using applicaiton metadata specified in the template. Customers just need to provide application metadata information in the template, then ``sam publish app`` will handle uploading local files -to S3 and creating the app. We will also provde sharing options to set application permission policies. This command will +to S3 and creating the app. We will also provide sharing options to set application permission policies. This command will greatly simplify the exsiting publishing experience. @@ -53,14 +53,12 @@ Out-of-Scope #. Manage application permission separately without publishing/updating the app. -#. Specify type of `application permission`_ in sharing options. +#. Specify granular permission types as defined in `application permission`_ when sharing the application. -#. Recursively publish nested apps in the template. +#. Recursively publish nested apps in the template (SAR CreateApplication API doesn't support yet). #. Run through CI/CD pipeline for the application before publishing. -#. Support downloading an app to edite/republish it. - #. Publish to other repositories besides SAR. #. Recognize template changes and suggest version number. @@ -105,7 +103,8 @@ Create new application in SAR created as 1.0.0. The app will be created as private by default. Create new version of an existing SAR application - Modify the existing template, give a different SemanticVersion value, and run ``sam publish app -t ./packaged.yaml``. + Modify the existing template, give a different SemanticVersion value, and run ``sam publish app -t ./packaged.yaml``. If + customers try to publish the same version again, the command will fail with an error message that the version already exists. Crete application/version and set application permission Run ``sam publish app -t ./packaged.yaml --make-public`` to publish the app and share it publicly. If ``--make-private`` @@ -145,8 +144,6 @@ CLI Changes 2. Update ``sam package`` command to support uploading locally referenced readme and license files to S3. -3. Update ``sam init`` command to support generating AWS::ServerlessRepo::Application section in the sample app template. - Breaking Change ~~~~~~~~~~~~~~~ *Are there any breaking changes to CLI interface? Explain* @@ -196,7 +193,15 @@ N/A **Are you connecting to a remote API? If so explain how is this connection secured** -N/A +Will be connecting to boto3 serverlessrepo `create_application`_, `update_application`_, `create_application_version`_, and `put_application_policy`_ +APIs through the `aws-serverlessrepo-python `_ library. The connection is secured by requiring +AWS credentials to connect to boto3. + +.. _create_application : https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/serverlessrepo.html#ServerlessApplicationRepository.Client.create_application +.. _update_application : https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/serverlessrepo.html#ServerlessApplicationRepository.Client.update_application +.. _create_application_version: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/serverlessrepo.html#ServerlessApplicationRepository.Client.create_application_version +.. _put_application_policy: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/serverlessrepo.html#ServerlessApplicationRepository.Client.put_application_policy + **Are you reading/writing to a temporary folder? If so, what is this used for and when do you clean up?** From 977fe04e85aaf1280cad67ba8639d84f90787cd0 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Wed, 5 Dec 2018 16:34:42 -0800 Subject: [PATCH 03/20] Remove --meta-data flag, include updating app metadata in sam publish app --- designs/sam_publish_app_cmd.rst | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index 1246828c23..3b9cf828ff 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -25,9 +25,9 @@ What will be changed? --------------------- In this proposal, we will be providing a new command, ``sam publish app``, which takes a SAM template as input and publishes an application to AWS Serverless Application Repository using applicaiton metadata specified in the template. Customers just -need to provide application metadata information in the template, then ``sam publish app`` will handle uploading local files -to S3 and creating the app. We will also provide sharing options to set application permission policies. This command will -greatly simplify the exsiting publishing experience. +need to provide application metadata information in the template, then ``sam package`` will handle uploading local files to S3, +and ``sam publish app`` will create the app in Serverless Application Repository. We will also provide sharing options to set +application permission policies. This command will greatly simplify the exsiting publishing experience. Success criteria for the change @@ -35,8 +35,8 @@ Success criteria for the change #. Support all the following use cases: * Create new application and its first version in SAR using ``sam publish app`` - * Update existing SAR application (metadata only) using ``sam publish app --meta-data`` * Create new version of existing SAR application using ``sam publish app`` + * Update application metadata of existing SAR application using ``sam publish app`` * Share the app publicly using the ``--make-public`` option * Make the app private using the ``--make-private`` option * Share the app privately with other AWS accounts using the ``--account-ids`` option @@ -49,8 +49,6 @@ Success criteria for the change Out-of-Scope ------------ -#. Create new application or version if the ``--meta-data`` option is used. - #. Manage application permission separately without publishing/updating the app. #. Specify granular permission types as defined in `application permission`_ when sharing the application. @@ -100,24 +98,26 @@ Package SAM template Create new application in SAR Run ``sam publish app -t ./packaged.yaml`` to publish a new application named my-app in SAR with the first version - created as 1.0.0. The app will be created as private by default. + created as 1.0.0. The app will be created as private by default. SAM CLI prints application created message and + link to the console details page. Create new version of an existing SAR application - Modify the existing template, give a different SemanticVersion value, and run ``sam publish app -t ./packaged.yaml``. If - customers try to publish the same version again, the command will fail with an error message that the version already exists. + Modify the existing template, give a different SemanticVersion value, and run ``sam publish app -t ./packaged.yaml``. + SAM CLI prints application metadata updated message, application version created message, values of the current application + metadata and link to the console details page. Crete application/version and set application permission Run ``sam publish app -t ./packaged.yaml --make-public`` to publish the app and share it publicly. If ``--make-private`` option is used, the app will only be visible to the owner. If ``--account-ids `` is used, the app will be shared with the provided AWS accounts. -Update the metadata of an exsiting application - Run ``sam publish app -t ./packaged.yaml --meta-data --application-id `` to update the application metadata. - Only changes to Description, Author, ReadmeUrl, Labels, and HomepageUrl will be honored because other fields are not - allowed to modify or are version specific. +Update the metadata of an exsiting application without creating new version + Keep SemanticVersion unchanged, then modify metadata fields like Description or ReadmeUrl, and run + ``sam publish app -t ./packaged.yaml``. SAM CLI prints application metadata updated message, values of the current + application metadata and link to the console details page. Output of the ``sam publish app`` command will be a link to the AWS Serverless Application Repository console details page -of the app just published. +of the app just published, and actions taken during publish (create application, update metadata w/ create application version). Implementation ============== @@ -130,8 +130,6 @@ CLI Changes -t, --template PATH AWS SAM template to publish. --region TEXT Set the AWS Region of the service (e.g. us-east-1). - --application-id TEXT Specify the application id to update. - --meta-data Update the application metadata. --make-public Share the app publicly with anyone. --make-private Share the app only with the owning account. --account-ids TEXT Share the app privately with the given comma-separated list @@ -142,7 +140,8 @@ CLI Changes by SAM CLI. --help Show this message and exit. -2. Update ``sam package`` command to support uploading locally referenced readme and license files to S3. +2. Update ``sam package`` (``aws cloudformation package``) command to support uploading locally referenced readme and +license files to S3. Breaking Change ~~~~~~~~~~~~~~~ From 08b5daf9327db8a70a067a8f3db19ed125d57f04 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Thu, 6 Dec 2018 13:31:08 -0800 Subject: [PATCH 04/20] Minor modifications --- designs/sam_publish_app_cmd.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index 3b9cf828ff..266469a832 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -44,8 +44,6 @@ Success criteria for the change #. ``sam package`` command can upload local readme/license files to S3. -#. sample app template generated by ``sam init`` will include the "AWS::ServerlessRepo::Application" section. - Out-of-Scope ------------ @@ -117,7 +115,7 @@ Update the metadata of an exsiting application without creating new version application metadata and link to the console details page. Output of the ``sam publish app`` command will be a link to the AWS Serverless Application Repository console details page -of the app just published, and actions taken during publish (create application, update metadata w/ create application version). +of the app just published, and actions taken during publish (create application or update metadata w/ create application version). Implementation ============== @@ -194,7 +192,7 @@ N/A Will be connecting to boto3 serverlessrepo `create_application`_, `update_application`_, `create_application_version`_, and `put_application_policy`_ APIs through the `aws-serverlessrepo-python `_ library. The connection is secured by requiring -AWS credentials to connect to boto3. +AWS credentials and permissions for the target application. .. _create_application : https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/serverlessrepo.html#ServerlessApplicationRepository.Client.create_application .. _update_application : https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/serverlessrepo.html#ServerlessApplicationRepository.Client.update_application @@ -227,7 +225,6 @@ Task Breakdown - [ ] Build the command line interface - [ ] Build the underlying library - [ ] Unit tests -- [ ] Functional Tests - [ ] Integration tests - [ ] Run all tests on Windows - [ ] Update documentation From adbcec9aacc3228c6ad02fe1ab56e8abb2479ab9 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Fri, 7 Dec 2018 17:13:35 -0800 Subject: [PATCH 05/20] Address comments --- designs/sam_publish_app_cmd.rst | 95 ++++++++++++++++++++++++--------- 1 file changed, 69 insertions(+), 26 deletions(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index 266469a832..cd3a8064a2 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -24,10 +24,10 @@ a mistake while typing in the command line. What will be changed? --------------------- In this proposal, we will be providing a new command, ``sam publish app``, which takes a SAM template as input and publishes -an application to AWS Serverless Application Repository using applicaiton metadata specified in the template. Customers just +an application to AWS Serverless Application Repository using applicaiton metadata specified in the template. Customers need to provide application metadata information in the template, then ``sam package`` will handle uploading local files to S3, and ``sam publish app`` will create the app in Serverless Application Repository. We will also provide sharing options to set -application permission policies. This command will greatly simplify the exsiting publishing experience. +application permission policies. Success criteria for the change @@ -49,7 +49,7 @@ Out-of-Scope ------------ #. Manage application permission separately without publishing/updating the app. -#. Specify granular permission types as defined in `application permission`_ when sharing the application. +#. Specify granular `application permission`_ types when sharing the application. If needed, customers can use AWS CLI instead as described `here`_. #. Recursively publish nested apps in the template (SAR CreateApplication API doesn't support yet). @@ -59,9 +59,10 @@ Out-of-Scope #. Recognize template changes and suggest version number. -#. Parse metadata from template without an AWS::ServerlessRepo::Application section. +#. Publish appication if ``AWS::ServerlessRepo::Application`` section is not found in the template's ``Metadata`` section. .. _application permission: https://docs.aws.amazon.com/serverlessrepo/latest/devguide/access-control-resource-based.html#application-permissions +.. _here: https://docs.aws.amazon.com/serverlessrepo/latest/devguide/access-control-resource-based.html#access-control-resource-based-example-multiple-permissions User Experience Walkthrough @@ -88,10 +89,16 @@ Assuming that customers have the following SAM template: HelloWorldFunction: Type: AWS::Lambda::Function Properties: - CodeUri: s3://bucket/hello-world + ... + CodeUri: ./source-code1 + ... -Package SAM template - Run ``sam package --template-file ./template.yaml --output-template-file packaged.yaml --s3-bucket my-bucket`` +Build Lambda source code + Run ``sam build -t template.yaml -b ./build -o built-template.yaml`` to build all functions in the template and output + a SAM template that can be run through the package command. + +Package built artifacts and local file references + Run ``sam package --template-file built-template.yaml --output-template-file packaged.yaml --s3-bucket my-bucket`` to upload code artifacts, readme and license files to S3 and generate the packaged template. Create new application in SAR @@ -104,10 +111,13 @@ Create new version of an existing SAR application SAM CLI prints application metadata updated message, application version created message, values of the current application metadata and link to the console details page. -Crete application/version and set application permission - Run ``sam publish app -t ./packaged.yaml --make-public`` to publish the app and share it publicly. If ``--make-private`` - option is used, the app will only be visible to the owner. If ``--account-ids `` is used, the app will be - shared with the provided AWS accounts. +Create application/version and set application permission + Run ``sam publish app -t ./packaged.yaml --make-public`` to publish the app and share it publicly so that everyone is + allowed to `Deploy`_ the app. Alternatively, use ``--account-ids `` to share with some AWS accounts. Only + you and the shared accounts can deploy the app. + + Customers can also revoke granted permissions and set the application back to be private, so it can + only be deployed by the owning account: ``sam publish app -t ./packaged.yaml --make-private`` Update the metadata of an exsiting application without creating new version Keep SemanticVersion unchanged, then modify metadata fields like Description or ReadmeUrl, and run @@ -115,7 +125,16 @@ Update the metadata of an exsiting application without creating new version application metadata and link to the console details page. Output of the ``sam publish app`` command will be a link to the AWS Serverless Application Repository console details page -of the app just published, and actions taken during publish (create application or update metadata w/ create application version). +of the app just published, message informing application created or application metadata updated w/ new application version +created, and the metadata fields that have been updated. + +Once the application is published, other developers in your team or your organization will be able to deploy it with a few +clicks. If the application is shared publicly, the whole community will be able to find it by visiting the AWS Serverless +Application Repository `public site`_. + +.. _Deploy: https://docs.aws.amazon.com/serverlessrepo/latest/devguide/access-control-resource-based.html#application-permissions +.. _public site: https://serverlessrepo.aws.amazon.com/applications + Implementation ============== @@ -124,19 +143,33 @@ CLI Changes ----------- *Explain the changes to command line interface, including adding new commands, modifying arguments etc* -1. Add a new top-level command called ``sam publish app`` with the following options. +1. Add a new top-level command called ``sam publish app`` with the following help message. + +.. code-block:: text + + Usage: samdev publish app [OPTIONS] - -t, --template PATH AWS SAM template to publish. - --region TEXT Set the AWS Region of the service (e.g. us-east-1). - --make-public Share the app publicly with anyone. - --make-private Share the app only with the owning account. - --account-ids TEXT Share the app privately with the given comma-separated list - of AWS account ids. - --profile TEXT Select a specific profile from your credential file to - get AWS credentials. - --debug Turn on debug logging to print debug message generated - by SAM CLI. - --help Show this message and exit. + Use this command to publish a packaged AWS SAM template to the AWS + Serverless Application Repository to share within your team, across your + organization, or with the community at large. + + This command expects the template's Metadata section to contain an + AWS::ServerlessRepo::Application section with application metadata + for publishing. For more details on this metadata section, see + https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverless-app-publishing-applications.html + + Options: + -t, --template PATH AWS SAM template file [default: template.[yaml|yml]] + --make-public Share the app publicly with anyone. + --make-private Share the app only with the owning account. + --account-ids TEXT Share the app privately with the given comma-separated + list of AWS account ids. + --profile TEXT Select a specific profile from your credential file to + get AWS credentials. + --region TEXT Set the AWS Region of the service (e.g. us-east-1). + --debug Turn on debug logging to print debug message generated + by SAM CLI. + --help Show this message and exit. 2. Update ``sam package`` (``aws cloudformation package``) command to support uploading locally referenced readme and license files to S3. @@ -211,8 +244,18 @@ N/A Documentation Changes --------------------- -We will document how to use the new ``sam publish app`` command for publishing SAR applications, and link to -the "AWS::ServerlessRepo::Application" sepc in CloudFormation documentation. +#. Add "AWS::ServerlessRepo::Application" sepc in `Publishing Applications`_ guide and document how to use ``sam publish app``. + +#. Add ``ReadmeUrl`` and ``LicenseUrl`` in `aws cloudformation package`_ documentation. + +#. Add ``sam publish app`` in `AWS SAM CLI Command Reference`_, and explain the command, usage, examples, options. + +#. Add a quick start guide "Publishing your application to AWS Serverless Application Repository" under SAM CLI `Get Started`_. + +.. _Publishing Applications: https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverless-app-publishing-applications.html +.. _aws cloudformation package: https://docs.aws.amazon.com/cli/latest/reference/cloudformation/package.html +.. _AWS SAM CLI Command Reference: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-command-reference.html +.. _Get Started: https://github.com/awslabs/aws-sam-cli#get-started Open Issues ----------- From 94d0cec12378708fd8378dc8479fd79963eafaa2 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Sun, 9 Dec 2018 16:36:46 -0800 Subject: [PATCH 06/20] Add examples in help text --- designs/sam_publish_app_cmd.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index cd3a8064a2..41843f9998 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -158,6 +158,20 @@ CLI Changes for publishing. For more details on this metadata section, see https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverless-app-publishing-applications.html + Examples + -------- + To publish an application privately using a packaged SAM template + $ sam publish app -t packaged.yaml --region + + To publish an application & share it publicly + $ sam publish app -t packaged.yaml --region --make-public + + To publish an application & share it with other AWS accounts + $ sam publish app -t packaged.yaml --region --account-ids 123456789012,123456789013 + + To publish an application & revoke granted permissions + $ sam publish app -t packaged.yaml --region --make-private + Options: -t, --template PATH AWS SAM template file [default: template.[yaml|yml]] --make-public Share the app publicly with anyone. From 71714651ca207683ebef734448f017fb6a8b7a2b Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Mon, 10 Dec 2018 11:06:12 -0800 Subject: [PATCH 07/20] Clarify default private, add CLI output example --- designs/sam_publish_app_cmd.rst | 83 +++++++++++++++++++++++++++------ 1 file changed, 69 insertions(+), 14 deletions(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index 41843f9998..83a03ab229 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -103,30 +103,85 @@ Package built artifacts and local file references Create new application in SAR Run ``sam publish app -t ./packaged.yaml`` to publish a new application named my-app in SAR with the first version - created as 1.0.0. The app will be created as private by default. SAM CLI prints application created message and - link to the console details page. + created as 1.0.0. If no permission option is passed, the app will be created as private by default. + + SAM CLI prints application created message, metadata used to create application and link to the console details page. + + >>> sam publish app -t ./packaged.yaml + Publish Succeeded + Created new application with the following metadata: + { + "Name": "my-app", + "Description": "hello world", + "Author": "user1", + "SpdxLicenseId": "Apache-2.0", + "LicenseUrl": "s3://test/LICENSE.txt", + "ReadmeUrl": "s3://test/README.md", + "Labels": ['tests'], + "HomepageUrl": "https://github.com/user1/my-app-project", + "SemanticVersion": "1.0.0", + "SourceCodeUrl": "https://github.com/user1/my-app-project" + } + Click the link below to view your application in AWS console: + https://console.aws.amazon.com/serverlessrepo/home?region=#/published-applications/ Create new version of an existing SAR application - Modify the existing template, give a different SemanticVersion value, and run ``sam publish app -t ./packaged.yaml``. - SAM CLI prints application metadata updated message, application version created message, values of the current application - metadata and link to the console details page. + Modify the existing template, give a new SemanticVersion, and run ``sam publish app -t ./packaged.yaml`` again. + + SAM CLI prints application metadata updated message and link to the console details page. If no permission option + is passed, the application's permission remains the same. + + >>> sam publish app -t ./packaged.yaml + Publish Succeeded + The following metadata of application has been updated: + { + "Author": "user1", + "Description": "description", + "ReadmeUrl": "s3://test/README.md", + ... + "SemanticVersion": "1.0.1", + "SourceCodeUrl": "https://github.com/hello" + } + Click the link below to view your application in AWS console: + https://console.aws.amazon.com/serverlessrepo/home?region=#/published-applications/ Create application/version and set application permission Run ``sam publish app -t ./packaged.yaml --make-public`` to publish the app and share it publicly so that everyone is - allowed to `Deploy`_ the app. Alternatively, use ``--account-ids `` to share with some AWS accounts. Only - you and the shared accounts can deploy the app. - - Customers can also revoke granted permissions and set the application back to be private, so it can - only be deployed by the owning account: ``sam publish app -t ./packaged.yaml --make-private`` + allowed to `Deploy`_ the app. Alternatively, use ``--account-ids `` to share with some AWS accounts so that + only you and the shared accounts can deploy the app. + + Customers can also revoke granted permissions and set the application back to be private using the ``--make-private`` option, + so that it can only be deployed by the owning account. + + >>> sam publish app -t ./packaged.yaml --make-public + Publish Succeeded + The following metadata of application has been updated: + { + "Author": "qwang", + "Description": "description", + "ReadmeUrl": "s3://test/README.md" + ... + } + Shared Application Publicly + Click the link below to view your application in AWS console: + https://console.aws.amazon.com/serverlessrepo/home?region=#/published-applications/ Update the metadata of an exsiting application without creating new version Keep SemanticVersion unchanged, then modify metadata fields like Description or ReadmeUrl, and run ``sam publish app -t ./packaged.yaml``. SAM CLI prints application metadata updated message, values of the current application metadata and link to the console details page. -Output of the ``sam publish app`` command will be a link to the AWS Serverless Application Repository console details page -of the app just published, message informing application created or application metadata updated w/ new application version -created, and the metadata fields that have been updated. + >>> sam publish app -t ./packaged.yaml + Publish Succeeded + The following metadata of application has been updated: + { + "Author": "qwang", + "Description": "description", + "ReadmeUrl": "s3://test/README.md" + ... + } + Click the link below to view your application in AWS console: + https://console.aws.amazon.com/serverlessrepo/home?region=#/published-applications/ Once the application is published, other developers in your team or your organization will be able to deploy it with a few clicks. If the application is shared publicly, the whole community will be able to find it by visiting the AWS Serverless @@ -209,7 +264,7 @@ library. The algorithm for ``sam publish app -t ./packaged.yaml --make-public`` with open('./packaged.yaml', 'r') as f: template = f.read() result = publish_application(template) - make_application_public(result.applicaiton_id) + make_application_public(result['applicaiton_id']) ``.samrc`` Changes From 94544095f9225bf6e2459e95d9ca661aaeff1fed Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Tue, 11 Dec 2018 11:01:10 -0800 Subject: [PATCH 08/20] Minor changes --- designs/sam_publish_app_cmd.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index 83a03ab229..b09c7983f5 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -82,7 +82,7 @@ Assuming that customers have the following SAM template: ReadmeUrl: ./README.md Labels: ['tests'] HomepageUrl: https://github.com/user1/my-app-project - SemanticVersion: 1.0.0 + SemanticVersion: 0.0.1 SourceCodeUrl: https://github.com/user1/my-app-project Resources: @@ -103,7 +103,7 @@ Package built artifacts and local file references Create new application in SAR Run ``sam publish app -t ./packaged.yaml`` to publish a new application named my-app in SAR with the first version - created as 1.0.0. If no permission option is passed, the app will be created as private by default. + created as 0.0.1. If no permission option is passed, the app will be created as private by default. SAM CLI prints application created message, metadata used to create application and link to the console details page. @@ -119,14 +119,14 @@ Create new application in SAR "ReadmeUrl": "s3://test/README.md", "Labels": ['tests'], "HomepageUrl": "https://github.com/user1/my-app-project", - "SemanticVersion": "1.0.0", + "SemanticVersion": "0.0.1", "SourceCodeUrl": "https://github.com/user1/my-app-project" } Click the link below to view your application in AWS console: https://console.aws.amazon.com/serverlessrepo/home?region=#/published-applications/ Create new version of an existing SAR application - Modify the existing template, give a new SemanticVersion, and run ``sam publish app -t ./packaged.yaml`` again. + Modify the existing template, change SemanticVersion to 0.0.2, and run ``sam publish app -t ./packaged.yaml`` again. SAM CLI prints application metadata updated message and link to the console details page. If no permission option is passed, the application's permission remains the same. @@ -139,7 +139,7 @@ Create new version of an existing SAR application "Description": "description", "ReadmeUrl": "s3://test/README.md", ... - "SemanticVersion": "1.0.1", + "SemanticVersion": "0.0.2", "SourceCodeUrl": "https://github.com/hello" } Click the link below to view your application in AWS console: @@ -202,7 +202,7 @@ CLI Changes .. code-block:: text - Usage: samdev publish app [OPTIONS] + Usage: sam publish app [OPTIONS] Use this command to publish a packaged AWS SAM template to the AWS Serverless Application Repository to share within your team, across your @@ -229,10 +229,10 @@ CLI Changes Options: -t, --template PATH AWS SAM template file [default: template.[yaml|yml]] - --make-public Share the app publicly with anyone. - --make-private Share the app only with the owning account. + --make-public Share the app publicly with anyone, mutually exclusive with --make-private and --account-ids. + --make-private Share the app only with the owning account, mutually exclusive with --make-public and --account-ids. --account-ids TEXT Share the app privately with the given comma-separated - list of AWS account ids. + list of AWS account ids, mutually exclusive with --make-public and --make-private. --profile TEXT Select a specific profile from your credential file to get AWS credentials. --region TEXT Set the AWS Region of the service (e.g. us-east-1). From 10eb646dc154175493ea88b240342afae67d44c9 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Tue, 11 Dec 2018 14:42:57 -0800 Subject: [PATCH 09/20] Remove make-public and make-private options --- designs/sam_publish_app_cmd.rst | 33 +++++++++++++++------------------ 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index b09c7983f5..450f8b1644 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -26,8 +26,8 @@ What will be changed? In this proposal, we will be providing a new command, ``sam publish app``, which takes a SAM template as input and publishes an application to AWS Serverless Application Repository using applicaiton metadata specified in the template. Customers need to provide application metadata information in the template, then ``sam package`` will handle uploading local files to S3, -and ``sam publish app`` will create the app in Serverless Application Repository. We will also provide sharing options to set -application permission policies. +and ``sam publish app`` will create the app in Serverless Application Repository. We will also provide the ``--acount-ids`` option +to configure who the application can be shared with. Success criteria for the change @@ -37,9 +37,9 @@ Success criteria for the change * Create new application and its first version in SAR using ``sam publish app`` * Create new version of existing SAR application using ``sam publish app`` * Update application metadata of existing SAR application using ``sam publish app`` - * Share the app publicly using the ``--make-public`` option - * Make the app private using the ``--make-private`` option - * Share the app privately with other AWS accounts using the ``--account-ids`` option + * Share the app publicly using ``--acount-ids ['*']`` + * Make the app private using ``--acount-ids []`` + * Share the app with other AWS accounts using ``--acount-ids ['123456789012']`` #. ``sam package`` command can upload local readme/license files to S3. @@ -146,14 +146,14 @@ Create new version of an existing SAR application https://console.aws.amazon.com/serverlessrepo/home?region=#/published-applications/ Create application/version and set application permission - Run ``sam publish app -t ./packaged.yaml --make-public`` to publish the app and share it publicly so that everyone is - allowed to `Deploy`_ the app. Alternatively, use ``--account-ids `` to share with some AWS accounts so that + Run ``sam publish app -t ./packaged.yaml --account-ids ['*']`` to publish the app and share it publicly so that everyone is + allowed to `Deploy`_ the app. Alternatively, use ``--account-ids [, ]`` to share with some AWS accounts so that only you and the shared accounts can deploy the app. - Customers can also revoke granted permissions and set the application back to be private using the ``--make-private`` option, + Customers can also revoke granted permissions and set the application back to be private using ``--account-ids []``, so that it can only be deployed by the owning account. - >>> sam publish app -t ./packaged.yaml --make-public + >>> sam publish app -t ./packaged.yaml --account-ids ['*'] Publish Succeeded The following metadata of application has been updated: { @@ -219,20 +219,17 @@ CLI Changes $ sam publish app -t packaged.yaml --region To publish an application & share it publicly - $ sam publish app -t packaged.yaml --region --make-public + $ sam publish app -t packaged.yaml --region --account-ids ['*'] To publish an application & share it with other AWS accounts - $ sam publish app -t packaged.yaml --region --account-ids 123456789012,123456789013 + $ sam publish app -t packaged.yaml --region --account-ids ['123456789012', '123456789013'] - To publish an application & revoke granted permissions - $ sam publish app -t packaged.yaml --region --make-private + To publish an application & revoke granted permissions to others + $ sam publish app -t packaged.yaml --region --account-ids [] Options: -t, --template PATH AWS SAM template file [default: template.[yaml|yml]] - --make-public Share the app publicly with anyone, mutually exclusive with --make-private and --account-ids. - --make-private Share the app only with the owning account, mutually exclusive with --make-public and --account-ids. - --account-ids TEXT Share the app privately with the given comma-separated - list of AWS account ids, mutually exclusive with --make-public and --make-private. + --account-ids TEXT Share the app with the given list of AWS account ids. --profile TEXT Select a specific profile from your credential file to get AWS credentials. --region TEXT Set the AWS Region of the service (e.g. us-east-1). @@ -255,7 +252,7 @@ Design *between components, constraints, etc.* SAM CLI will read the packaged SAM template and pass it as string to `aws-serverlessrepo-python `_ -library. The algorithm for ``sam publish app -t ./packaged.yaml --make-public`` looks like this: +library. The algorithm for ``sam publish app -t ./packaged.yaml --account-ids ['*']`` looks like this: .. code-block:: python From cddb013357e43f29a1495cfa93f464ce3d9e7888 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Tue, 11 Dec 2018 15:02:52 -0800 Subject: [PATCH 10/20] Clarify about not managing permisison without --acount-ids --- designs/sam_publish_app_cmd.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index 450f8b1644..cb7deb33f0 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -215,7 +215,7 @@ CLI Changes Examples -------- - To publish an application privately using a packaged SAM template + To publish an application without managing permissions $ sam publish app -t packaged.yaml --region To publish an application & share it publicly From fefb085489da85220f27de447f4d0830c87b13e5 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Tue, 11 Dec 2018 16:25:36 -0800 Subject: [PATCH 11/20] Remove use case for making an app private, change --account-ids to accept string --- designs/sam_publish_app_cmd.rst | 26 ++++++++++---------------- 1 file changed, 10 insertions(+), 16 deletions(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index cb7deb33f0..eee0588e11 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -37,9 +37,8 @@ Success criteria for the change * Create new application and its first version in SAR using ``sam publish app`` * Create new version of existing SAR application using ``sam publish app`` * Update application metadata of existing SAR application using ``sam publish app`` - * Share the app publicly using ``--acount-ids ['*']`` - * Make the app private using ``--acount-ids []`` - * Share the app with other AWS accounts using ``--acount-ids ['123456789012']`` + * Share the app publicly using ``--acount-ids '*'`` + * Share the app with other AWS accounts using ``--acount-ids 123456789012`` #. ``sam package`` command can upload local readme/license files to S3. @@ -146,14 +145,11 @@ Create new version of an existing SAR application https://console.aws.amazon.com/serverlessrepo/home?region=#/published-applications/ Create application/version and set application permission - Run ``sam publish app -t ./packaged.yaml --account-ids ['*']`` to publish the app and share it publicly so that everyone is - allowed to `Deploy`_ the app. Alternatively, use ``--account-ids [, ]`` to share with some AWS accounts so that + Run ``sam publish app -t ./packaged.yaml --account-ids '*'`` to publish the app and share it publicly so that everyone is + allowed to `Deploy`_ the app. Alternatively, use ``--account-ids ,`` to share with some AWS accounts so that only you and the shared accounts can deploy the app. - Customers can also revoke granted permissions and set the application back to be private using ``--account-ids []``, - so that it can only be deployed by the owning account. - - >>> sam publish app -t ./packaged.yaml --account-ids ['*'] + >>> sam publish app -t ./packaged.yaml --account-ids '*' Publish Succeeded The following metadata of application has been updated: { @@ -219,17 +215,15 @@ CLI Changes $ sam publish app -t packaged.yaml --region To publish an application & share it publicly - $ sam publish app -t packaged.yaml --region --account-ids ['*'] + $ sam publish app -t packaged.yaml --region --account-ids '*' To publish an application & share it with other AWS accounts - $ sam publish app -t packaged.yaml --region --account-ids ['123456789012', '123456789013'] - - To publish an application & revoke granted permissions to others - $ sam publish app -t packaged.yaml --region --account-ids [] + $ sam publish app -t packaged.yaml --region --account-ids 123456789012,123456789013 Options: -t, --template PATH AWS SAM template file [default: template.[yaml|yml]] - --account-ids TEXT Share the app with the given list of AWS account ids. + --account-ids TEXT Share the app with the given comma-separated list of AWS account ids. + If '*' is specified, the app will be shared publicly. --profile TEXT Select a specific profile from your credential file to get AWS credentials. --region TEXT Set the AWS Region of the service (e.g. us-east-1). @@ -252,7 +246,7 @@ Design *between components, constraints, etc.* SAM CLI will read the packaged SAM template and pass it as string to `aws-serverlessrepo-python `_ -library. The algorithm for ``sam publish app -t ./packaged.yaml --account-ids ['*']`` looks like this: +library. The algorithm for ``sam publish app -t ./packaged.yaml --account-ids '*'`` looks like this: .. code-block:: python From 1f51100d275a9658a5f5f8ace5ddaad737893d24 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Tue, 11 Dec 2018 17:20:43 -0800 Subject: [PATCH 12/20] Fix typos --- designs/sam_publish_app_cmd.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index eee0588e11..0e9dfc75f6 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -6,7 +6,7 @@ ==================================== This is the design for a command to publish an application to `AWS Serverless Application Repository (SAR)`_ with a SAM -template. It can be used to create a new application and its first version, update exisitng application's metadata, create +template. It can be used to create a new application and its first version, update existing application's metadata, create a new version of the application, and manage application permissions. .. _AWS Serverless Application Repository (SAR): https://aws.amazon.com/serverless/serverlessrepo/ @@ -26,7 +26,7 @@ What will be changed? In this proposal, we will be providing a new command, ``sam publish app``, which takes a SAM template as input and publishes an application to AWS Serverless Application Repository using applicaiton metadata specified in the template. Customers need to provide application metadata information in the template, then ``sam package`` will handle uploading local files to S3, -and ``sam publish app`` will create the app in Serverless Application Repository. We will also provide the ``--acount-ids`` option +and ``sam publish app`` will create the app in Serverless Application Repository. We will also provide the ``--account-ids`` option to configure who the application can be shared with. @@ -37,8 +37,8 @@ Success criteria for the change * Create new application and its first version in SAR using ``sam publish app`` * Create new version of existing SAR application using ``sam publish app`` * Update application metadata of existing SAR application using ``sam publish app`` - * Share the app publicly using ``--acount-ids '*'`` - * Share the app with other AWS accounts using ``--acount-ids 123456789012`` + * Share the app publicly using ``--account-ids '*'`` + * Share the app with other AWS accounts using ``--account-ids 123456789012`` #. ``sam package`` command can upload local readme/license files to S3. @@ -162,7 +162,7 @@ Create application/version and set application permission Click the link below to view your application in AWS console: https://console.aws.amazon.com/serverlessrepo/home?region=#/published-applications/ -Update the metadata of an exsiting application without creating new version +Update the metadata of an existing application without creating new version Keep SemanticVersion unchanged, then modify metadata fields like Description or ReadmeUrl, and run ``sam publish app -t ./packaged.yaml``. SAM CLI prints application metadata updated message, values of the current application metadata and link to the console details page. From dd18e878e4451be45beb801e3211ada4d1bc5946 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Tue, 11 Dec 2018 21:56:21 -0800 Subject: [PATCH 13/20] Remove managing application permissions from scope --- designs/sam_publish_app_cmd.rst | 56 ++++++--------------------------- 1 file changed, 10 insertions(+), 46 deletions(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index 0e9dfc75f6..f611b68629 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -6,8 +6,8 @@ ==================================== This is the design for a command to publish an application to `AWS Serverless Application Repository (SAR)`_ with a SAM -template. It can be used to create a new application and its first version, update existing application's metadata, create -a new version of the application, and manage application permissions. +template. It can be used to create a new application w/ its first version, update existing application's metadata, and +create new versions of the application. .. _AWS Serverless Application Repository (SAR): https://aws.amazon.com/serverless/serverlessrepo/ @@ -26,29 +26,23 @@ What will be changed? In this proposal, we will be providing a new command, ``sam publish app``, which takes a SAM template as input and publishes an application to AWS Serverless Application Repository using applicaiton metadata specified in the template. Customers need to provide application metadata information in the template, then ``sam package`` will handle uploading local files to S3, -and ``sam publish app`` will create the app in Serverless Application Repository. We will also provide the ``--account-ids`` option -to configure who the application can be shared with. +and ``sam publish app`` will create the app in Serverless Application Repository. Success criteria for the change ------------------------------- #. Support all the following use cases: - * Create new application and its first version in SAR using ``sam publish app`` + * Create new application w/ its first version in SAR using ``sam publish app`` * Create new version of existing SAR application using ``sam publish app`` * Update application metadata of existing SAR application using ``sam publish app`` - * Share the app publicly using ``--account-ids '*'`` - * Share the app with other AWS accounts using ``--account-ids 123456789012`` - #. ``sam package`` command can upload local readme/license files to S3. Out-of-Scope ------------ -#. Manage application permission separately without publishing/updating the app. - -#. Specify granular `application permission`_ types when sharing the application. If needed, customers can use AWS CLI instead as described `here`_. +#. Manage application permissions while publishing the app. #. Recursively publish nested apps in the template (SAR CreateApplication API doesn't support yet). @@ -60,7 +54,6 @@ Out-of-Scope #. Publish appication if ``AWS::ServerlessRepo::Application`` section is not found in the template's ``Metadata`` section. -.. _application permission: https://docs.aws.amazon.com/serverlessrepo/latest/devguide/access-control-resource-based.html#application-permissions .. _here: https://docs.aws.amazon.com/serverlessrepo/latest/devguide/access-control-resource-based.html#access-control-resource-based-example-multiple-permissions @@ -144,24 +137,6 @@ Create new version of an existing SAR application Click the link below to view your application in AWS console: https://console.aws.amazon.com/serverlessrepo/home?region=#/published-applications/ -Create application/version and set application permission - Run ``sam publish app -t ./packaged.yaml --account-ids '*'`` to publish the app and share it publicly so that everyone is - allowed to `Deploy`_ the app. Alternatively, use ``--account-ids ,`` to share with some AWS accounts so that - only you and the shared accounts can deploy the app. - - >>> sam publish app -t ./packaged.yaml --account-ids '*' - Publish Succeeded - The following metadata of application has been updated: - { - "Author": "qwang", - "Description": "description", - "ReadmeUrl": "s3://test/README.md" - ... - } - Shared Application Publicly - Click the link below to view your application in AWS console: - https://console.aws.amazon.com/serverlessrepo/home?region=#/published-applications/ - Update the metadata of an existing application without creating new version Keep SemanticVersion unchanged, then modify metadata fields like Description or ReadmeUrl, and run ``sam publish app -t ./packaged.yaml``. SAM CLI prints application metadata updated message, values of the current @@ -183,7 +158,6 @@ Once the application is published, other developers in your team or your organiz clicks. If the application is shared publicly, the whole community will be able to find it by visiting the AWS Serverless Application Repository `public site`_. -.. _Deploy: https://docs.aws.amazon.com/serverlessrepo/latest/devguide/access-control-resource-based.html#application-permissions .. _public site: https://serverlessrepo.aws.amazon.com/applications @@ -211,19 +185,11 @@ CLI Changes Examples -------- - To publish an application without managing permissions + To publish an application $ sam publish app -t packaged.yaml --region - To publish an application & share it publicly - $ sam publish app -t packaged.yaml --region --account-ids '*' - - To publish an application & share it with other AWS accounts - $ sam publish app -t packaged.yaml --region --account-ids 123456789012,123456789013 - Options: -t, --template PATH AWS SAM template file [default: template.[yaml|yml]] - --account-ids TEXT Share the app with the given comma-separated list of AWS account ids. - If '*' is specified, the app will be shared publicly. --profile TEXT Select a specific profile from your credential file to get AWS credentials. --region TEXT Set the AWS Region of the service (e.g. us-east-1). @@ -246,16 +212,15 @@ Design *between components, constraints, etc.* SAM CLI will read the packaged SAM template and pass it as string to `aws-serverlessrepo-python `_ -library. The algorithm for ``sam publish app -t ./packaged.yaml --account-ids '*'`` looks like this: +library. The algorithm for ``sam publish app -t ./packaged.yaml`` looks like this: .. code-block:: python - from serverlessrepo import publish_application, make_application_public + from serverlessrepo import publish_application with open('./packaged.yaml', 'r') as f: template = f.read() result = publish_application(template) - make_application_public(result['applicaiton_id']) ``.samrc`` Changes @@ -283,14 +248,13 @@ N/A **Are you connecting to a remote API? If so explain how is this connection secured** -Will be connecting to boto3 serverlessrepo `create_application`_, `update_application`_, `create_application_version`_, and `put_application_policy`_ -APIs through the `aws-serverlessrepo-python `_ library. The connection is secured by requiring +Will be connecting to boto3 serverlessrepo `create_application`_, `update_application`_, `create_application_version`_ APIs through +the `aws-serverlessrepo-python `_ library. The connection is secured by requiring AWS credentials and permissions for the target application. .. _create_application : https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/serverlessrepo.html#ServerlessApplicationRepository.Client.create_application .. _update_application : https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/serverlessrepo.html#ServerlessApplicationRepository.Client.update_application .. _create_application_version: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/serverlessrepo.html#ServerlessApplicationRepository.Client.create_application_version -.. _put_application_policy: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/serverlessrepo.html#ServerlessApplicationRepository.Client.put_application_policy **Are you reading/writing to a temporary folder? If so, what is this used for and when do you clean up?** From 841e8466255a442a4e795cd408b13acc16e3c3e6 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Wed, 12 Dec 2018 11:07:14 -0800 Subject: [PATCH 14/20] Remove mention of permissions --- designs/sam_publish_app_cmd.rst | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index f611b68629..7cd895f9b6 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -54,8 +54,6 @@ Out-of-Scope #. Publish appication if ``AWS::ServerlessRepo::Application`` section is not found in the template's ``Metadata`` section. -.. _here: https://docs.aws.amazon.com/serverlessrepo/latest/devguide/access-control-resource-based.html#access-control-resource-based-example-multiple-permissions - User Experience Walkthrough --------------------------- @@ -95,9 +93,8 @@ Package built artifacts and local file references Create new application in SAR Run ``sam publish app -t ./packaged.yaml`` to publish a new application named my-app in SAR with the first version - created as 0.0.1. If no permission option is passed, the app will be created as private by default. - - SAM CLI prints application created message, metadata used to create application and link to the console details page. + created as 0.0.1. The app will be created as private by default. SAM CLI prints application created message, metadata + used to create application and link to the console details page. >>> sam publish app -t ./packaged.yaml Publish Succeeded @@ -119,9 +116,7 @@ Create new application in SAR Create new version of an existing SAR application Modify the existing template, change SemanticVersion to 0.0.2, and run ``sam publish app -t ./packaged.yaml`` again. - - SAM CLI prints application metadata updated message and link to the console details page. If no permission option - is passed, the application's permission remains the same. + SAM CLI prints application metadata updated message, values of updated metadata and link to the console details page. >>> sam publish app -t ./packaged.yaml Publish Succeeded @@ -139,8 +134,8 @@ Create new version of an existing SAR application Update the metadata of an existing application without creating new version Keep SemanticVersion unchanged, then modify metadata fields like Description or ReadmeUrl, and run - ``sam publish app -t ./packaged.yaml``. SAM CLI prints application metadata updated message, values of the current - application metadata and link to the console details page. + ``sam publish app -t ./packaged.yaml``. SAM CLI prints application metadata updated message, values of updated + metadata and link to the console details page. >>> sam publish app -t ./packaged.yaml Publish Succeeded From a1a5f85e7acd77d31c15390d12ae087ed9868f6a Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Thu, 13 Dec 2018 13:26:34 -0800 Subject: [PATCH 15/20] Update documentation changes needed --- designs/sam_publish_app_cmd.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index 7cd895f9b6..ab7381c7f0 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -263,18 +263,22 @@ N/A Documentation Changes --------------------- -#. Add "AWS::ServerlessRepo::Application" sepc in `Publishing Applications`_ guide and document how to use ``sam publish app``. +1. SAM specification updates: -#. Add ``ReadmeUrl`` and ``LicenseUrl`` in `aws cloudformation package`_ documentation. + - Add "AWS::ServerlessRepo::Application" sepc in `SAM specification`. -#. Add ``sam publish app`` in `AWS SAM CLI Command Reference`_, and explain the command, usage, examples, options. + - Point to the new SAM spec in `Publishing Applications`_ guide. -#. Add a quick start guide "Publishing your application to AWS Serverless Application Repository" under SAM CLI `Get Started`_. +2. Add ``ReadmeUrl`` and ``LicenseUrl`` in `aws cloudformation package`_ documentation. +3. Add ``sam publish app`` in `AWS SAM CLI Command Reference`_, and explain the command, usage, examples, options. + +4. Add a quick start guide "Publishing your application to AWS Serverless Application Repository" explaining how to use ``sam publish app``. + +.. _SAM Spec: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md .. _Publishing Applications: https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverless-app-publishing-applications.html .. _aws cloudformation package: https://docs.aws.amazon.com/cli/latest/reference/cloudformation/package.html .. _AWS SAM CLI Command Reference: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-command-reference.html -.. _Get Started: https://github.com/awslabs/aws-sam-cli#get-started Open Issues ----------- From f990b6c834aa76d6b22e7a0b7643db32374ebdb3 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Mon, 17 Dec 2018 12:53:15 -0800 Subject: [PATCH 16/20] Remove subcommand app --- designs/sam_publish_app_cmd.rst | 44 ++++++++++++++++----------------- 1 file changed, 21 insertions(+), 23 deletions(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index ab7381c7f0..13e415d2c1 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -2,7 +2,7 @@ :depth: 2 :local: -``sam publish app`` command +``sam publish`` command ==================================== This is the design for a command to publish an application to `AWS Serverless Application Repository (SAR)`_ with a SAM @@ -23,19 +23,19 @@ a mistake while typing in the command line. What will be changed? --------------------- -In this proposal, we will be providing a new command, ``sam publish app``, which takes a SAM template as input and publishes +In this proposal, we will be providing a new command, ``sam publish``, which takes a SAM template as input and publishes an application to AWS Serverless Application Repository using applicaiton metadata specified in the template. Customers need to provide application metadata information in the template, then ``sam package`` will handle uploading local files to S3, -and ``sam publish app`` will create the app in Serverless Application Repository. +and ``sam publish`` will create the app in Serverless Application Repository. Success criteria for the change ------------------------------- #. Support all the following use cases: - * Create new application w/ its first version in SAR using ``sam publish app`` - * Create new version of existing SAR application using ``sam publish app`` - * Update application metadata of existing SAR application using ``sam publish app`` + * Create new application w/ its first version in SAR using ``sam publish`` + * Create new version of existing SAR application using ``sam publish`` + * Update application metadata of existing SAR application using ``sam publish`` #. ``sam package`` command can upload local readme/license files to S3. @@ -92,11 +92,11 @@ Package built artifacts and local file references to upload code artifacts, readme and license files to S3 and generate the packaged template. Create new application in SAR - Run ``sam publish app -t ./packaged.yaml`` to publish a new application named my-app in SAR with the first version + Run ``sam publish -t ./packaged.yaml`` to publish a new application named my-app in SAR with the first version created as 0.0.1. The app will be created as private by default. SAM CLI prints application created message, metadata used to create application and link to the console details page. - >>> sam publish app -t ./packaged.yaml + >>> sam publish -t ./packaged.yaml Publish Succeeded Created new application with the following metadata: { @@ -115,10 +115,10 @@ Create new application in SAR https://console.aws.amazon.com/serverlessrepo/home?region=#/published-applications/ Create new version of an existing SAR application - Modify the existing template, change SemanticVersion to 0.0.2, and run ``sam publish app -t ./packaged.yaml`` again. + Modify the existing template, change SemanticVersion to 0.0.2, and run ``sam publish -t ./packaged.yaml`` again. SAM CLI prints application metadata updated message, values of updated metadata and link to the console details page. - >>> sam publish app -t ./packaged.yaml + >>> sam publish -t ./packaged.yaml Publish Succeeded The following metadata of application has been updated: { @@ -134,10 +134,10 @@ Create new version of an existing SAR application Update the metadata of an existing application without creating new version Keep SemanticVersion unchanged, then modify metadata fields like Description or ReadmeUrl, and run - ``sam publish app -t ./packaged.yaml``. SAM CLI prints application metadata updated message, values of updated + ``sam publish -t ./packaged.yaml``. SAM CLI prints application metadata updated message, values of updated metadata and link to the console details page. - >>> sam publish app -t ./packaged.yaml + >>> sam publish -t ./packaged.yaml Publish Succeeded The following metadata of application has been updated: { @@ -163,11 +163,11 @@ CLI Changes ----------- *Explain the changes to command line interface, including adding new commands, modifying arguments etc* -1. Add a new top-level command called ``sam publish app`` with the following help message. +1. Add a new top-level command called ``sam publish`` with the following help message. .. code-block:: text - Usage: sam publish app [OPTIONS] + Usage: sam publish [OPTIONS] Use this command to publish a packaged AWS SAM template to the AWS Serverless Application Repository to share within your team, across your @@ -181,7 +181,7 @@ CLI Changes Examples -------- To publish an application - $ sam publish app -t packaged.yaml --region + $ sam publish -t packaged.yaml --region Options: -t, --template PATH AWS SAM template file [default: template.[yaml|yml]] @@ -207,7 +207,7 @@ Design *between components, constraints, etc.* SAM CLI will read the packaged SAM template and pass it as string to `aws-serverlessrepo-python `_ -library. The algorithm for ``sam publish app -t ./packaged.yaml`` looks like this: +library. The algorithm for ``sam publish -t ./packaged.yaml`` looks like this: .. code-block:: python @@ -263,19 +263,17 @@ N/A Documentation Changes --------------------- -1. SAM specification updates: +1. Add "AWS::ServerlessRepo::Application" spec in `Publishing Applications`_ guide. - - Add "AWS::ServerlessRepo::Application" sepc in `SAM specification`. - - - Point to the new SAM spec in `Publishing Applications`_ guide. + - Can be added in `SAM specification`_ in the future. 2. Add ``ReadmeUrl`` and ``LicenseUrl`` in `aws cloudformation package`_ documentation. -3. Add ``sam publish app`` in `AWS SAM CLI Command Reference`_, and explain the command, usage, examples, options. +3. Add ``sam publish`` in `AWS SAM CLI Command Reference`_, and explain the command, usage, examples, options. -4. Add a quick start guide "Publishing your application to AWS Serverless Application Repository" explaining how to use ``sam publish app``. +4. Add a quick start guide "Publishing your application to AWS Serverless Application Repository" explaining how to use ``sam publish``. -.. _SAM Spec: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md +.. _SAM specification: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md .. _Publishing Applications: https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverless-app-publishing-applications.html .. _aws cloudformation package: https://docs.aws.amazon.com/cli/latest/reference/cloudformation/package.html .. _AWS SAM CLI Command Reference: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-command-reference.html From 508efb99812bc46490ae1ff8a38259fdc0e10ab6 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Fri, 21 Dec 2018 17:22:42 -0800 Subject: [PATCH 17/20] Change doc link --- designs/sam_publish_app_cmd.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_app_cmd.rst index 13e415d2c1..0eb1350959 100644 --- a/designs/sam_publish_app_cmd.rst +++ b/designs/sam_publish_app_cmd.rst @@ -176,7 +176,7 @@ CLI Changes This command expects the template's Metadata section to contain an AWS::ServerlessRepo::Application section with application metadata for publishing. For more details on this metadata section, see - https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverless-app-publishing-applications.html + https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-publishing-applications.html Examples -------- From 38562a716aefc4dda13a9846b2df91bdb7eecdae Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Fri, 21 Dec 2018 17:30:12 -0800 Subject: [PATCH 18/20] Change doc link in helper text --- samcli/commands/publish/command.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/samcli/commands/publish/command.py b/samcli/commands/publish/command.py index 4697d5b1b2..77eebedab2 100644 --- a/samcli/commands/publish/command.py +++ b/samcli/commands/publish/command.py @@ -22,7 +22,7 @@ This command expects the template's Metadata section to contain an AWS::ServerlessRepo::Application section with application metadata for publishing. For more details on this metadata section, see -https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverless-app-publishing-applications.html +https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-publishing-applications.html \b Examples -------- From 3ca187c248469ee2727cafdcadab40dc0ce1c210 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Tue, 25 Dec 2018 13:02:26 -0800 Subject: [PATCH 19/20] Rename sam publish design doc --- designs/{sam_publish_app_cmd.rst => sam_publish_cmd.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename designs/{sam_publish_app_cmd.rst => sam_publish_cmd.rst} (100%) diff --git a/designs/sam_publish_app_cmd.rst b/designs/sam_publish_cmd.rst similarity index 100% rename from designs/sam_publish_app_cmd.rst rename to designs/sam_publish_cmd.rst From 4c19f8ea20a1b797efed10a18c91e942dc97fcd6 Mon Sep 17 00:00:00 2001 From: Vicky Wang Date: Thu, 3 Jan 2019 13:13:30 -0800 Subject: [PATCH 20/20] Fix HomePageUrl typo --- designs/sam_publish_cmd.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/designs/sam_publish_cmd.rst b/designs/sam_publish_cmd.rst index 0eb1350959..45b2de3dd2 100644 --- a/designs/sam_publish_cmd.rst +++ b/designs/sam_publish_cmd.rst @@ -71,7 +71,7 @@ Assuming that customers have the following SAM template: LicenseUrl: ./LICENSE.txt ReadmeUrl: ./README.md Labels: ['tests'] - HomepageUrl: https://github.com/user1/my-app-project + HomePageUrl: https://github.com/user1/my-app-project SemanticVersion: 0.0.1 SourceCodeUrl: https://github.com/user1/my-app-project @@ -107,7 +107,7 @@ Create new application in SAR "LicenseUrl": "s3://test/LICENSE.txt", "ReadmeUrl": "s3://test/README.md", "Labels": ['tests'], - "HomepageUrl": "https://github.com/user1/my-app-project", + "HomePageUrl": "https://github.com/user1/my-app-project", "SemanticVersion": "0.0.1", "SourceCodeUrl": "https://github.com/user1/my-app-project" }