Package during `sam deploy` ==================================== What is the problem? -------------------- Today while using `sam deploy` the specified `--template-file` or `--template` is expected to have packaged artifacts references in the given template file. This is driven by the following workflow. `sam build` -> `sam package --s3-bucket ... --s3-prefix ... --output-template-file packaged.yaml`. This workflow builds the requisite code and packages those built artifacts into an s3 bucket, optionally under a given s3 prefix. If a developer can optionally cut through this process without requiring an explicit `package` command, but rather have `sam deploy` package to a given s3 bucket, it cuts the number of steps before needing to deploy and test in the cloud. This also reduces friction in the `author` and `test` loop. Ideal end state. `sam build` -> `sam deploy ..... --s3-bucket ....` What will be changed? --------------------- Addition of extra parameters that are currently supported by `sam package` over to `sam deploy` with all of them being optional. Additional parameters that need to be on `sam deploy` that are not on `sam package`. * `--metadata` * `--use-json` Parameters that dont need to be added. * `--output-template-file` * An explicit `output-template-file` is created on the fly during packaging in the deploy phase. If the expectation is to package and deploy in one command, One can now do. `sam deploy --stack-name sam-package-on-deploy --capabilities CAPABILITY_IAM --s3-bucket sam-package-bucket` There is no explicit need to pass in a `--template-file` or `--template` parameter, if one is not passed in it to defaults to trying to find the template.yaml that was generated by `sam build` which is located at `.aws-sam/build/template.yaml` The old method of deploying pre-packaged artifacts will continue to work as before. * `sam deploy --template-file packaged.yaml --stack-name sam-package-on-deploy --capabilities CAPABILITY_IAM` If a deployment is done without running `sam build` prior we still go ahead and deploy with the given `template.yaml` in the project root. This might still result in a successful deploy, but not a deploy with the correct build artifacts. Future of `sam package`? --------------------- * `sam package` will continue to exist in the state it is today and will continue to be improved upon separately. Success criteria for the change ------------------------------- User do not require to run `sam package` as part of their author test loop, except for CI/CD purposes, where `sam package` can be run and the packaged template file can be passed to cloudformation deploy actions. Out-of-Scope ------------ The s3 bucket where the packaged artifacts go is not abstracted in this design. In the future, the s3 bucket could be specified via a configuration file. This is currently in design in : https://github.com/awslabs/aws-sam-cli/pull/1503 User Experience Walkthrough --------------------------- `sam build` -> `sam deploy` `sam build` -> `sam package` -> `sam deploy` Provide identical experiences in terms of a deploying the same stack, with exactly same artifacts. Implementation ============== CLI Changes ----------- * Add new arguments `--metadata`, `--use-json` and modify existing `--template-file` or `--template` to look for a default `template.yaml` that exists under `.aws-sam/build/` ### Breaking Change * Not a breaking change , but there are optional behavorial changes that a user can subscribe into by supplying a non-packaged template file and an s3 bucket. Design ------ * Changes to Deploy command's click options * Attempt to package on every deploy if an appropriate s3 bucket is specified and deploy using the output template file during package. * If a pre-packaged template is specified, an attempt to package does not change the template and the same template is used for deploy. * The parameters that share the same name across package and deploy are collapsed together. eg: `--kms-key-id` , if a kms-key-id is specified that same key is used across both packaging and deploy purposes. `.samrc` Changes ---------------- None Security -------- **What new dependencies (libraries/cli) does this change require?** N/A **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?** Possibly reading from a configuration file in the future. **How do you validate new .samrc configuration?** N/A What is your Testing Plan (QA)? =============================== Goal ---- * Regression tests on previous functionality of `sam deploy` * Integration tests on automatic packaging on `sam deploy` Pre-requesites -------------- N/A Test Scenarios/Cases -------------------- * Re-deploy a stack that was deployed with a packaged template before hand using the new sam deploy menthod. `sam deploy --template-file packaged.yaml --stack-name sam-stack --capabilities CAPABILITY_IAM` `sam deploy --stack-name sam-stack --capabilities CAPABILITY_IAM` The new stack should not have any changes. Expected Results ---------------- * Regresssion and Integration tests pass. Documentation Changes ===================== * Required nature of `--template-file`, `--template` parameter has a series of defaults that are looked at during `sam deploy` similair to `sam package`. * If `--template-file` or `--template` points to a non-packaged template-file, `--s3-bucket` becomes required to be able to effectively package and deploy in one command using `sam deploy`. Open Issues ============ 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