From 68b7485c0783708233970aff3a9f574414e2da59 Mon Sep 17 00:00:00 2001 From: dmonk Date: Mon, 21 Nov 2022 15:15:23 -0600 Subject: [PATCH] Update penlink/tye repo reademe for changes made --- docs/recipes/githubactions_aks.md | 12 +-- docs/recipes/ingress.md | 2 +- .../commandline/tye-build-push-deploy.md | 100 ++++++++++++++++++ docs/reference/commandline/tye-build.md | 3 + docs/reference/commandline/tye-deploy.md | 14 ++- docs/reference/commandline/tye-push.md | 12 ++- docs/reference/deployment.md | 8 +- docs/reference/schema.md | 4 + docs/tutorials/hello-tye/01_deploy.md | 14 +-- src/tye/Program.BuildCommand.cs | 2 +- 10 files changed, 145 insertions(+), 26 deletions(-) create mode 100644 docs/reference/commandline/tye-build-push-deploy.md diff --git a/docs/recipes/githubactions_aks.md b/docs/recipes/githubactions_aks.md index 2f594c14e..d2a3420a4 100644 --- a/docs/recipes/githubactions_aks.md +++ b/docs/recipes/githubactions_aks.md @@ -64,7 +64,7 @@ Next, ensure that Tye and its dependent .NET runtime are installed. dotnet tool install -g Microsoft.Tye --version "0.11.0-alpha.22111.1" ``` -Using the name of the registry and the [Azure docker action](https://github.com/Azure/docker-login) to login to your registry. This step is needed prior to running the `deploy` command which will build and push the images to the registry. +Using the name of the registry and the [Azure docker action](https://github.com/Azure/docker-login) to login to your registry. This step is needed prior to running the `build-push-deploy` command which will build and push the images to the registry. >:bulb: The username and password for authentication is stored in [secrets](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) within the GitHub repository. @@ -105,9 +105,9 @@ Finally, deploy the application! >:bulb: adding the `-v Debug` for verbose logging ```yaml -- name: ☸ tye deploy +- name: ☸ tye build-push-deploy run: | - tye deploy -v Debug + tye build-push-deploy -v Debug ``` ### Complete GitHub Action @@ -125,7 +125,7 @@ env: jobs: build: if: github.event_name == 'push' && contains(toJson(github.event.commits), '***NO_CI***') == false && contains(toJson(github.event.commits), '[ci skip]') == false && contains(toJson(github.event.commits), '[skip ci]') == false - name: tye deploy + name: build-push-deploy runs-on: ubuntu-latest steps: - name: ✔ Checkout @@ -158,9 +158,9 @@ jobs: run: | kubectl apply -f https://aka.ms/tye/ingress/deploy - - name: ☸ tye deploy + - name: ☸ tye build-push-deploy run: | - tye deploy -v Debug + tye build-push-deploy -v Debug ``` ## Viewing the deployed application diff --git a/docs/recipes/ingress.md b/docs/recipes/ingress.md index b46327288..515727c66 100644 --- a/docs/recipes/ingress.md +++ b/docs/recipes/ingress.md @@ -142,7 +142,7 @@ These steps should still function if you have already deployed the NGINX Ingress To deploy the application - do an interactive deployment from the terminal: ``` -tye deploy --interactive +tye build-push-deploy --interactive ``` We're using an interactive deployment because Tye will need to prompt for: diff --git a/docs/reference/commandline/tye-build-push-deploy.md b/docs/reference/commandline/tye-build-push-deploy.md new file mode 100644 index 000000000..5dceaf3f9 --- /dev/null +++ b/docs/reference/commandline/tye-build-push-deploy.md @@ -0,0 +1,100 @@ +# tye build-push-deploy + +## Name + +`tye build-push-deploy` - Deploys the application to Kubernetes. + +## Synopsis + +```text +tye build-push-deploy [-?|-h|--help] [-i|--interactive] [-v|--verbosity ] [-n|--namespace ] [-f|--framework ] [--tags ] [--force] [] +``` + +## Description + +The `tye build-push-deploy` command will deploy an application to Kubernetes. `tye build-push-deploy` by default will: + +- Create a docker image for each project in your application. +- Push each docker image to your container registry. +- Generate a Kubernetes Deployment and Service for each project. +- Apply the generated Deployment and Service to your current Kubernetes context. + +`tye build-push-deploy` chooses the Kubernetes namespace to operate in according to the following priority: + +- The value of `--namespace` passed at the command line +- The value of `namespace` configured in `tye.yaml` (if present) +- The Kubernetes namespace for the current context + +> :bulb: Use `kubectl config view --minify --output 'jsonpath={..namespace}'` to view the current namespace. + +> :warning: The `tye build-push-deploy` command requires access to a remote container registry. Images will be tagged using the registry configured in `tye.yaml` (if present), or using a registry supplied interactively at the command line. + +> :bulb: The `tye build-push-deploy` command uses Docker's credentials for pushing to the remote container registry. Make sure Docker is configured to push to your registry before running `tye build-push-deploy`. + +> :bulb: The `tye build-push-deploy` command uses your local Kubernetes context to access the Kubernetes cluster. Make sure `kubectl` is configured to manage your cluster before running `tye build-push-deploy`. + +## Arguments + +`PATH` + +The path to either a file or directory to execute `tye build-push-deploy` on. Can either be a yaml, sln, or project file, however it is recommend to have a tye.yaml file for `tye build-push-deploy`. + +If a directory path is specified, `tye build-push-deploy` will default to using these files, in the following order: + +- `tye.yaml` +- `*.sln` +- `*.csproj/*.fsproj` + +## Options + +- `-i|--interactive` + + Does an interactive deployment that will accept input for values that are required by default. + +- `-v|--verbosity ` + + The verbosity of logs emitted by `tye build-push-deploy`. Defaults to Info. + +- `-n|--namespace` + + Specifies the Kubernetes namespace for deployment. Overrides a namespace value set in `tye.yaml`. + +- `-f|--framework ` + + The target framework hint to use for all cross-targeting projects with multiple TFMs. This value must be a valid target framework for each individual cross-targeting project. Non-crosstargeting projects will ignore this hint and the value TFM configured in tye.yaml will override this hint. + +- `--tags ` + + Filter the group of running services by tag. + + `-e|--environment ` + + The environment to be used for deployment. Defaults to development if not specified. + + `-d|--debug` + + Enables debug mode. Waits for the debugger to attach to the process before starting. + +- `--force` + + Override validation and forces deployment. + +## Examples + +- Deploy an application from the current directory: + + ```text + tye build-push-deploy + ``` + +- Deploy an application with interactive input: + + ```text + tye build-push-deploy --interactive + ``` + +- Deploy an application, increasing log verbosity to Debug. + + ```text + tye build-push-deploy --verbosity Debug + ``` diff --git a/docs/reference/commandline/tye-build.md b/docs/reference/commandline/tye-build.md index b9ff521ec..a3ff38733 100644 --- a/docs/reference/commandline/tye-build.md +++ b/docs/reference/commandline/tye-build.md @@ -46,6 +46,9 @@ If a directory path is specified, `tye build` will default to using these files, The target framework hint to use for all cross-targeting projects with multiple TFMs. This value must be a valid target framework for each individual cross-targeting project. Non-crosstargeting projects will ignore this hint and the value TFM configured in tye.yaml will override this hint. + `-e|--environment ` + + The environment to be used for deployment. Defaults to development if not specified. ## Examples diff --git a/docs/reference/commandline/tye-deploy.md b/docs/reference/commandline/tye-deploy.md index d93bc6d8e..a29e32289 100644 --- a/docs/reference/commandline/tye-deploy.md +++ b/docs/reference/commandline/tye-deploy.md @@ -14,8 +14,6 @@ tye deploy [-?|-h|--help] [-i|--interactive] [-v|--verbosity ] The `tye deploy` command will deploy an application to Kubernetes. `tye deploy` by default will: -- Create a docker image for each project in your application. -- Push each docker image to your container registry. - Generate a Kubernetes Deployment and Service for each project. - Apply the generated Deployment and Service to your current Kubernetes context. @@ -27,9 +25,7 @@ The `tye deploy` command will deploy an application to Kubernetes. `tye deploy` > :bulb: Use `kubectl config view --minify --output 'jsonpath={..namespace}'` to view the current namespace. -> :warning: The `tye deploy` command requires access to a remote container registry. Images will be tagged using the registry configured in `tye.yaml` (if present), or using a registry supplied interactively at the command line. - -> :bulb: The `tye deploy` command uses Docker's credentials for pushing to the remote container registry. Make sure Docker is configured to push to your registry before running `tye deploy`. +> :warning: The `tye deploy` command assumes that the configured image name and tag have already been pushed to the registry. Make sure the image used already exists. > :bulb: The `tye deploy` command uses your local Kubernetes context to access the Kubernetes cluster. Make sure `kubectl` is configured to manage your cluster before running `tye deploy`. @@ -67,6 +63,14 @@ If a directory path is specified, `tye deploy` will default to using these files Filter the group of running services by tag. + `-e|--environment ` + + The environment to be used for deployment. Defaults to development if not specified. + + `-d|--debug` + + Enables debug mode. Waits for the debugger to attach to the process before starting. + - `--force` Override validation and forces deployment. diff --git a/docs/reference/commandline/tye-push.md b/docs/reference/commandline/tye-push.md index 18e43c87a..6b72c53ce 100644 --- a/docs/reference/commandline/tye-push.md +++ b/docs/reference/commandline/tye-push.md @@ -40,7 +40,7 @@ If a directory path is specified, `tye push` will default to using these files, - `-v|--verbosity ` - The verbosity of logs emitted by `tye deploy`. Defaults to Info. + The verbosity of logs emitted by `tye build-push-deploy`. Defaults to Info. - `--tags ` @@ -50,6 +50,14 @@ If a directory path is specified, `tye push` will default to using these files, The target framework hint to use for all cross-targeting projects with multiple TFMs. This value must be a valid target framework for each individual cross-targeting project. Non-crosstargeting projects will ignore this hint and the value TFM configured in tye.yaml will override this hint. + `-e|--environment ` + + The environment to be used for deployment. Defaults to development if not specified. + + `--include-latest-tag` + + Push a docker image with 'latest' tag as well as versioned tag. + - `--force` Override validation and force push. @@ -71,5 +79,5 @@ If a directory path is specified, `tye push` will default to using these files, - Push an application, increasing log verbosity to Debug. ```text - tye deploy --verbosity Debug + tye build-push-deploy --verbosity Debug ``` diff --git a/docs/reference/deployment.md b/docs/reference/deployment.md index b9734e99d..d212511d9 100644 --- a/docs/reference/deployment.md +++ b/docs/reference/deployment.md @@ -1,14 +1,14 @@ # Deployment -*This document is a conceptual overview of how Tye behaves when using `tye deploy` for deployment. For reference docs on the `tye deploy` command see the [command line doc](/docs/reference/commandline/tye-deploy.md).* +*This document is a conceptual overview of how Tye behaves when using `tye build-push-deploy` for deployment. For reference docs on the `tye build-push-deploy` command see the [command line doc](/docs/reference/commandline/tye-build-push-deploy.md).* Tye simplifies many of the common concerns when deploying services, including creating docker files, docker images, Kubernetes manifests, and service discovery. This document will describe how these features work, as well as the implications and behaviors of various optional settings. -## Executing `tye deploy` +## Executing `tye build-push-deploy` -When executing `tye deploy`, Tye goes through the following steps for each project: +When executing `tye build-push-deploy`, Tye goes through the following steps for each project: - Configure defaults for docker - Compute bindings @@ -23,7 +23,7 @@ These steps are sequentially executed for each project or service. Sets defaults for any projects that will create docker images. For example, for any ASP.NET Core projects, this step will set the container base image to `mcr.microsoft.com/dotnet/core/aspnet`. It will also select the image tag based on the .NET version specified (2.1, 3.1, 5, 6, etc.). -This is also where Tye requires a container registry to properly set the image name. If running `tye deploy` (no interactive), tye requires a registry to be defined in `tye.yaml`. If running interactively (`tye deploy -i`), tye will prompt the user for one if not specified in `tye.yaml`. +This is also where Tye requires a container registry to properly set the image name. If running `tye build-push-deploy` (no interactive), tye requires a registry to be defined in `tye.yaml`. If running interactively (`tye build-push-deploy -i`), tye will prompt the user for one if not specified in `tye.yaml`. ### Compute bindings diff --git a/docs/reference/schema.md b/docs/reference/schema.md index 66b73e4eb..c73b1a99c 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -182,6 +182,10 @@ Build arguments to use when building a Docker image. This is only used when `doc Path to the Dockerfile Context to run docker build against. This is only used when `dockerFile` is specified as well. +#### `dockerImageVersion` (string) + +Version of the docker image to be built. Defaults to the current timestamp if not specified. + #### `executable` (string) The path (or filename) of an executable to launch. diff --git a/docs/tutorials/hello-tye/01_deploy.md b/docs/tutorials/hello-tye/01_deploy.md index d71efe11f..00dee2e61 100644 --- a/docs/tutorials/hello-tye/01_deploy.md +++ b/docs/tutorials/hello-tye/01_deploy.md @@ -2,7 +2,7 @@ This tutorial assumes that you have completed the [first step (run locally)](00_run_locally.md) -> :bulb: `tye` will use your current credentials for pushing Docker images and accessing kubernetes clusters. If you have configured kubectl with a context already, that's what [`tye deploy`](/docs/reference/commandline/tye-deploy.md) is going to use! +> :bulb: `tye` will use your current credentials for pushing Docker images and accessing kubernetes clusters. If you have configured kubectl with a context already, that's what [`tye build-push-deploy`](/docs/reference/commandline/tye-build-push-deploy.md) is going to use! Before we deploy, make sure you have the following ready... @@ -21,24 +21,24 @@ Before we deploy, make sure you have the following ready... ## Deploying the application -Now that we have our application running locally, let's deploy the application. In this example, we will deploy to Kubernetes by using `tye deploy`. +Now that we have our application running locally, let's deploy the application. In this example, we will deploy to Kubernetes by using `tye build-push-deploy`. 1. Deploy to Kubernetes Deploy the application by running: ```text - tye deploy --interactive + tye build-push-deploy --interactive ``` > Enter the Container Registry (ex: 'example.azurecr.io' for Azure or 'example' for dockerhub): You will be prompted to enter your container registry. This is needed to tag images, and to push them to a location accessible by kubernetes. - > :bulb: Under the hood `tye` uses `kubectl` to execute deployments. In cases where you don't have `kubectl` installed or it's current context is invalid `tye deploy` will fail with the following error: "Drats! 'deploy' failed: Cannot apply manifests because kubectl is not installed." + > :bulb: Under the hood `tye` uses `kubectl` to execute deployments. In cases where you don't have `kubectl` installed or it's current context is invalid `tye build-push-deploy` will fail with the following error: "Drats! 'build-push-deploy' failed: Cannot apply manifests because kubectl is not installed." If you are using dockerhub, the registry name will be your dockerhub username. If you use a standalone container registry (for instance from your cloud provider), the registry name will look like a hostname, eg: `example.azurecr.io`. - `tye deploy` does many different things to deploy an application to Kubernetes. It will: + `tye build-push-deploy` does many different things to deploy an application to Kubernetes. It will: - Create a docker image for each project in your application. - Push each docker image to your container registry. - Generate a Kubernetes `Deployment` and `Service` for each project. @@ -85,7 +85,7 @@ Now that we have our application running locally, let's deploy the application. ## Exploring tye.yaml -Tye has a optional configuration file (`tye.yaml`) to allow customizing settings. If you want to use `tye deploy` as part of a CI/CD system, it's expected that you'll have a `tye.yaml`. +Tye has a optional configuration file (`tye.yaml`) to allow customizing settings. If you want to use `tye build-push-deploy` as part of a CI/CD system, it's expected that you'll have a `tye.yaml`. 1. Scaffolding `tye.yaml` @@ -130,7 +130,7 @@ Tye has a optional configuration file (`tye.yaml`) to allow customizing settings If you are using dockerhub, the registry_name will your dockerhub username. If you use a standalone container registry (for instance from your cloud provider), the registry_name will look like a hostname, eg: `example.azurecr.io`. - Now it's possible to use `tye deploy` without `--interactive` since the registry is stored as part of configuration. + Now it's possible to use `tye build-push-deploy` without `--interactive` since the registry is stored as part of configuration. > :question: This step may not make much sense if you're using `tye.yaml` to store a personal Dockerhub username. A more typical use case would be storing the name of a private registry for use in a CI/CD system. diff --git a/src/tye/Program.BuildCommand.cs b/src/tye/Program.BuildCommand.cs index d7dc2488a..8f86cd611 100644 --- a/src/tye/Program.BuildCommand.cs +++ b/src/tye/Program.BuildCommand.cs @@ -36,7 +36,7 @@ public static Command CreateBuildCommand() var filter = ApplicationFactoryFilter.GetApplicationFactoryFilter(args.Tags); - return BuildHost.BuildAsync(output, args.Path, args.Interactive, args.Environment,args.Framework, filter); + return BuildHost.BuildAsync(output, args.Path, args.Interactive, args.Environment, args.Framework, filter); }); return command;