From a81783d37061317da7f4b92ad8f08cb3268ee519 Mon Sep 17 00:00:00 2001 From: Alistair Matthews Date: Thu, 7 Dec 2023 15:40:03 +0000 Subject: [PATCH 1/2] Deploy to to Kubernetes by using the Aspirate tool (#134) * K8s deployment doc added * Continued with deployment to k8s * Completed K8s deployment doc * Completed K8s deployment doc. * Added a link to the Aspirate NuGet page * Fixed two build errors * Fixed issues from @IEvangelist * Another grammar fix. * Code blocks fixed and TOC entry added * Completed the TOC entry for K8s deployment --------- Co-authored-by: AJ Matthews --- docs/deployment/k8s-deployment.md | 181 ++++++++++++++++++++++++++++++ docs/toc.yml | 4 + 2 files changed, 185 insertions(+) create mode 100644 docs/deployment/k8s-deployment.md diff --git a/docs/deployment/k8s-deployment.md b/docs/deployment/k8s-deployment.md new file mode 100644 index 000000000..391d71ec1 --- /dev/null +++ b/docs/deployment/k8s-deployment.md @@ -0,0 +1,181 @@ +--- +title: Deploy .NET Aspire apps to a Kubernetes cluster +description: Learn how to use the Aspirate tool to deploy .NET Aspire apps to a Kubernetes cluster. +ms.date: 12/06/2023 +--- + +# Deploy .NET Aspire apps to a Kubernetes cluster + +.NET Aspire helps you to create cloud-native apps that are divided into microservices. Each microservice is designed to run in a containerized environment. By deploying .NET Aspire apps to a Kubernetes cluster, you can benefit from Kubernetes' advanced container management features. This article will explain how to deploy a completed .NET Aspire solution to a Kubernetes cluster by using the [Aspirate tool](https://www.nuget.org/packages/Aspirate). You'll learn: + +> [!div class="checklist"] +> +> - The prerequisites that must be in placed for the Aspirate tool. +> - How .NET Aspire and Kubernetes manifest files differ. +> - How to install and initialize the Aspirate tool. +> - How to create and manifests and containers and deploy them to a Kubernetes cluster. + +[!INCLUDE [aspire-prereqs](../includes/aspire-prereqs.md)] + +## Aspirate prerequisites + +In addition to the .NET Aspire prerequisites, the Aspirate tool needs the following to be in place before you can use it to deploy a .NET Aspire app: + +- A container registry. You can either specify the location of the registry in the .NET Aspire manifest file or configure it when you run Aspirate for the first time. After Aspirate builds the app, it uploads the resulting container images to this registry. +- The [Kuberbetes CLI tool](https://kubernetes.io/docs/tasks/tools/), `kubectl`, installed on the computer where you will run Aspirate. +- A Kubernetes cluster. The Kubernetes CLI tool must be configured to connect to this cluster in the **kubeconfig** file. + +## Compare manifest formats + +Manifest files are used in many application development and hosting platforms to describe the components of an app. .NET Aspire can create manifest files that help tool developers to create deployment code. Kubernetes also uses manifest files to describe how the system should create and manage resources in the cluster. However, these two types of manifest file have completely different formats and are not interchangeable. + +A .NET Aspire manifest file is in JSON format and describes each project in the solution file, bindings to other projects, configuration values, and other properties. This example includes a web front end, a back end API service, and a Redis cache component: + +```json +{ + "resources": { + "cache": { + "type": "redis.v0" + }, + "apiservice": { + "type": "project.v0", + "path": "..\\AspireApp.ApiService\\AspireApp.ApiService.csproj", + "env": { + "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES": "true", + "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES": "true" + }, + "bindings": { + "http": { + "scheme": "http", + "protocol": "tcp", + "transport": "http" + }, + "https": { + "scheme": "https", + "protocol": "tcp", + "transport": "http" + } + } + }, + "webfrontend": { + "type": "project.v0", + "path": "..\\AspireApp.Web\\AspireApp.Web.csproj", + "env": { + "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES": "true", + "OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES": "true", + "ConnectionStrings__cache": "{cache.connectionString}", + "services__apiservice__0": "{apiservice.bindings.http.url}", + "services__apiservice__1": "{apiservice.bindings.https.url}" + }, + "bindings": { + "http": { + "scheme": "http", + "protocol": "tcp", + "transport": "http" + }, + "https": { + "scheme": "https", + "protocol": "tcp", + "transport": "http" + } + } + } + } +} +``` + +> [!NOTE] +> For more information about .NET Aspire manifest files, see [.NET Aspire manifest format for deployment tool builders](manifest-format.md) + +Kubernetes manifest files are in YAML format and describe the desired state for a cluster. Kubernetes automatically manages pods, containers, and services to meet the desired state: + +```yaml +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: webfrontend +spec: + minReadySeconds: 60 + replicas: 1 + selector: + matchLabels: + app: webfrontend + strategy: + rollingUpdate: + maxUnavailable: 0 + maxSurge: 1 + template: + metadata: + labels: + app: webfrontend + spec: + containers: + - name: webfrontend + image: localhost:5000/webfrontend:latest + imagePullPolicy: Always + ports: + - containerPort: 8080 + envFrom: + - configMapRef: + name: webfrontend-env + terminationGracePeriodSeconds: 180 +``` + +You can use the Aspirate tool to create the Kubernetes manifest files and containers and deploy them to a cluster. + +## Install Aspirate + +To install Aspirate, use the `dotnet tool` command: + +```dotnetcli +dotnet tool install -g aspirate --prerelease +``` + +> [!NOTE] +> At the time of writing, the Aspirate tool is in preview and the `--prerelease` option is required. + +## Initialize Aspirate + +Aspirate takes three settings from the project file for the .NET Aspire AppHost project: + +- **ContainerRegistry**: The location of a Docker image registry. Aspirate stores the images it creates in this registry and deploys to the Kubernetes cluster from there. +- **ContainerTag**: Aspirate adds this tag to the Docker images it creates. +- **TemplatePath**: Modifies the default path to Visual Studio template that Aspirate transforms into manifests. + +You can manually set these values in the project file, or issue this command: + +```dotnetcli +aspirate init +``` + +Aspirate leads you through the process of setting these values and persists them in an _aspirate.json_ file. + +## Create manifests + +To create Kubernetes manifests for the projects in your solution, use the `generate` command. Before you issue the command, change to the top-level folder for your _*.AppHost_ project: + +```dotnetcli +cd AspireApp.AppHost +aspirate generate +``` + +The `generate` command: + +- Creates Kubernetes manifest file for each component in the solution and stores them in the _aspirate-output_ subfolder. +- Prompts for you to select components to build. +- Builds the projects you specify. +- Pushes the built containers to the **ContainerRegistry** you specified in the `init` command. + +> [!NOTE] +> The `aspirate build` command is similar to the `generate` command. It creates manifest files, builds projects, and pushes the containers to the registry by default. However, if you use the `--aspire-manifest` option, you can use an existing .NET Aspire manifest file. + +## Install containers in a Kubernetes cluster + +Once the containers are built and stored in your registry, you can use Aspirate to run them on your Kubernetes cluster: + +```dotnetcli +aspirate apply +``` + +The command runs the containers on the cluster specified in your _kubeconfig_ file. diff --git a/docs/toc.yml b/docs/toc.yml index 2bf556070..4b6aa25a1 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -103,6 +103,10 @@ items: href: deployment/azure/aca-deployment-azd-in-depth.md - name: Use .NET Aspire with Application Insights href: deployment/azure/application-insights.md + - name: Kubernetes + items: + - name: Deploy .NET Aspire apps to a Kubernetes cluster + href: deployment/k8s-deployment.md - name: Reference - Tool-builder manifest schemas href: deployment/manifest-format.md From e47bfcfbd1720b71edb380cc5d8fde5a212dc236 Mon Sep 17 00:00:00 2001 From: alexwolfmsft <93200798+alexwolfmsft@users.noreply.github.com> Date: Thu, 7 Dec 2023 10:48:27 -0500 Subject: [PATCH 2/2] Update index landing page and links to include new tutorial and match TOC verbiage. (#138) * update index to match toc * fix --- docs/index.yml | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/index.yml b/docs/index.yml index 534f6dd21..8a6c245e3 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -65,8 +65,8 @@ conceptualContent: - title: Storage links: - - itemType: quickstart - text: Connect to storage with .NET Aspire + - itemType: tutorial + text: Tutorial - Connect to storage with .NET Aspire url: storage/azure-storage.md - itemType: how-to-guide text: Azure Blob Storage @@ -80,29 +80,32 @@ conceptualContent: - title: Database links: + - itemType: quickstart + text: Tutorial - Connect to SQL Server with EF Core + url: database/quickstart-sql-server.md - itemType: how-to-guide text: PostgreSQL database url: database/postgresql-component.md - itemType: how-to-guide - text: PostgreSQL with Entity Framework Core + text: PostgreSQL with EF Core url: database/postgresql-entity-framework-component.md - itemType: how-to-guide text: Azure Cosmos DB url: database/azure-cosmos-db-component.md - itemType: how-to-guide - text: Azure Cosmos DB with Entity Framework Core + text: Azure Cosmos DB with EF Core url: database/azure-cosmos-db-entity-framework-component.md - itemType: how-to-guide text: SQL Database url: database/sql-server-component.md - itemType: how-to-guide - text: SQL Database with Entity Framework Core + text: SQL Database with EF Core url: database/sql-server-entity-framework-component.md - title: Messaging links: - - itemType: quickstart - text: Implement Messaging with .NET Aspire + - itemType: tutorial + text: Tutorial - Implement Messaging with .NET Aspire url: messaging/quickstart-messaging.md - itemType: overview text: Azure Service Bus @@ -113,8 +116,8 @@ conceptualContent: - title: Caching links: - - itemType: quickstart - text: Improve app caching with .NET Aspire + - itemType: tutorial + text: Tutorial - Improve app caching with .NET Aspire url: caching/quickstart-caching.md - itemType: how-to-guide text: Redis caching