Design doc for spk service create

technical-docs/designs/services/acrBuildArguments.md

@@ -0,0 +1,103 @@
+# Software Design Document: Passing arguments to a Dockerfile during `az acr build` execution
+
+Reference: An option to pass environment variables while building a Dockerfile
+<br> Authors: Bhargav Nookala, Evan Louie, James Spring, Michael Tarng, Yvonne
+Radsmikham
+
+| Revision | Date         | Author            | Remarks       |
+| -------: | ------------ | ----------------- | ------------- |
+|      0.1 | Mar-26, 2020 | Yvonne Radsmikham | Initial Draft |
+
+## 1. Overview
+
+This design will enhance the developer experience for using
+`spk service create`. Currently, the concern is that building of the Dockerfile
+assumes there are no inputs into the build process. This is handled in a script
+task of the `build` stage in the `build-update-hld.yaml`, which is generated
+when `spk service create` is executed.
+
+Snippet of `build-update-hld.yaml`:
+
+```yaml
+    - script: |-
+        set -e
+        export BUILD_REPO_NAME=$(echo $(Build.Repository.Name)-fabrikam.acme.frontend | tr '[:upper:]' '[:lower:]')
+        export IMAGE_TAG=$(echo $(Build.SourceBranchName) | tr / - | tr . - | tr _ - )-$(Build.BuildNumber)
+        export IMAGE_NAME=$BUILD_REPO_NAME:$IMAGE_TAG
+        echo "Image Name: $IMAGE_NAME"
+        cd ./services/fabrikam.acme.frontend
+        echo "az acr build -r $(ACR_NAME) --image $IMAGE_NAME ."
+        az acr build -r $(ACR_NAME) --image $IMAGE_NAME .
+    displayName: ACR Build and Publish
+```
+
+## 2. Out of Scope
+
+This design shall only aim to make user experience better by adding new features
+to service creation.
+
+## 3. Design Details
+
+### 3.1 Add new arguments for `spk service create` to link or create variable groups
+
+As part of `spk service create`, add the following features:
+
+- Create a new command argument `--build-vg` to link an existing variable group
+  or create a new variable group with variables to be passed into a Docker build
+  execution.
+
+- Add argument `--build-variables` to take in an array of key-value pairs for
+  all variables to be used in an existing or new variable group. This argument
+  will support secret variables if specified.
+
+Example:
+
+```sh
+spk service create "fabrikam.acme.frontend" -d "services" -p "chart" -g "https://dev.azure.com/bedrock/fabrikam/_git/fabrikam2019" -b "master" --build-vg "my-azdo-build-vg" --build-variables [version:0.0.1,path:$HOME,apikey:key:isSecret]
+```
+
+To do this, we would be leveraging `spk project cvg` or
+`spk variable-group create`. This _can_ be done as a **prerequisite** for using
+the `build-vg` and `--build-variables`. For example, if the user is providing a
+variable group name that does not exist, we may return an error message to
+enforce that they create the variable group first with the appropriate variables
+to use by executing `spk project cvg` or `spk variable-group create` beforehand.
+
+As part of the build-update-hld.yaml, where there is the "ACR Build and Publish"
+task
+([L208](https://github.com/CatalystCode/spk/blob/7fd1606a6e6ad0a4622a8be2f20fe3a0c17e5a82/src/lib/fileutils.ts#L208)-[L217](https://github.com/CatalystCode/spk/blob/7fd1606a6e6ad0a4622a8be2f20fe3a0c17e5a82/src/lib/fileutils.ts#L217))
+generated by `spk service create`, we can add logic to iterate through the
+variable array assocciated with a variable group and inject variables as
+arguments to be part of the `az acr build` command
+(i.e.`az acr build -r $(ACR_NAME) -f $(DOCKER_BUILD_FILE) --build-arg $key=${value}`).
+In the `build-update-hld.yaml`, this would imply that each variable that needs
+to be passed into the Dockerfile will need to be exported (i.e.
+`export PATH=${PATH}`) as an environment variable so that it can be captured in
+the build command.
+
+The iteration should be conditional, meaning if there are no variable groups
+linked, then the assumption is made that there are no arguments needed to be
+passed into the build process, and in which case the build process will continue
+as how it is working currently.
+
+## 4. Dependencies
+
+None
+
+## 5. Known issues
+
+None
+
+## 6. Risks & Mitigations
+
+There needs to be proper error handling when dealing with naming collisions in
+creating new variable groups or adding new variables to existing variable
+groups.
+
+## 7. Documentation
+
+Documentation should be done in the
+[`md` file](https://github.com/CatalystCode/spk/blob/master/src/commands/service/create.md)
+that are associated with `spk service create` command.
+
+\- end -