From 5b27f1c5db35e4054eac0a3b7fba7cca88b5a706 Mon Sep 17 00:00:00 2001 From: David Pine Date: Fri, 29 Mar 2024 10:07:15 -0500 Subject: [PATCH 1/4] Add new article to fix #551 --- docs/deployment/manifest-format.md | 19 ++++- docs/index.yml | 3 + docs/toc.yml | 6 ++ .../allow-unsecure-transport.md | 73 +++++++++++++++++++ 4 files changed, 100 insertions(+), 1 deletion(-) create mode 100644 docs/troubleshooting/allow-unsecure-transport.md diff --git a/docs/deployment/manifest-format.md b/docs/deployment/manifest-format.md index 2762222162..2c7f4f0ae2 100644 --- a/docs/deployment/manifest-format.md +++ b/docs/deployment/manifest-format.md @@ -1,7 +1,7 @@ --- title: .NET Aspire manifest format for deployment tool builders description: Learn about the .NET Aspire manifest format in this comprehensive deployment tool builder guide. -ms.date: 03/13/2024 +ms.date: 03/29/2024 ms.topic: reference --- @@ -44,6 +44,23 @@ info: Aspire.Hosting.Publishing.ManifestPublisher[0] The file generated is the .NET Aspire manifest and is used by tools to support deploying into target cloud environments. +> [!TIP] +> You can also generate a manifest as part of the launch profile. Consider the following _launchSettings.json_: +> +> ```json +> { +> "$schema": "http://json.schemastore.org/launchsettings.json", +> "profiles": { +> "generate-manifest": { +> "commandName": "Project", +> "launchBrowser": false, +> "dotnetRunMessages": true, +> "commandLineArgs": "--publisher manifest --output-path aspire-manifest.json" +> } +> } +> } +> ``` + ## Basic manifest format Publishing the manifest from the default starter template for .NET Aspire produces the following JSON output: diff --git a/docs/index.yml b/docs/index.yml index 522bb6a2b0..5121b6bca9 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -124,6 +124,9 @@ conceptualContent: - itemType: how-to-guide text: RabbitMQ client .NET Aspire component url: messaging/rabbitmq-client-component.md + - itemType: how-to-guide + text: Apache Kafka + url: messaging/kafka-component.md - title: Caching links: diff --git a/docs/toc.yml b/docs/toc.yml index 230cad8fd4..c485a21beb 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -154,6 +154,12 @@ items: - name: Reference - Tool-builder manifest schemas href: deployment/manifest-format.md + - name: Troubleshooting + items: + - name: Allow unsecure transport + displayName: unsecure transport,http,non-tls + href: troubleshooting/allow-unsecure-transport.md + - name: Resources items: - name: .NET Aspire diff --git a/docs/troubleshooting/allow-unsecure-transport.md b/docs/troubleshooting/allow-unsecure-transport.md new file mode 100644 index 0000000000..8965146861 --- /dev/null +++ b/docs/troubleshooting/allow-unsecure-transport.md @@ -0,0 +1,73 @@ +--- +title: Allow unsecure transport in .NET Aspire +description: Learn how to allow unsecure transport in .NET Aspire applications. +ms.date: 03/29/2024 +--- + +# Allow unsecure transport in .NET Aspire + +Starting with .NET Aspire preview 5, the app host will crash if an `applicationUrl` is configured with an insecure transport (non-TLS `http`) protocol. This is a security feature to prevent accidental exposure of sensitive data. However, there are scenarios where you might need to allow unsecure transport. This article explains how to allow unsecure transport in .NET Aspire applications. + +## Symptoms + +When you run a .NET Aspire application with an `applicationUrl` configured with an insecure transport protocol, you might see the following error message: + +```plaintext +The 'applicationUrl' setting must be an https address unless the +'ASPIRE_ALLOW_UNSECURED_TRANSPORT' environment variable is set to true. + +This configuration is commonly set in the launch profile. +``` + +## How to allow unsecure transport + +To allow an unsecure transport in .NET Aspire, set the `ASPIRE_ALLOW_UNSECURED_TRANSPORT` environment variable to `true`. This environment variable is used to control the behavior of the app host when an `applicationUrl` is configured with an insecure transport protocol: + +## [Unix](#tab/unix) + +```bash +export ASPIRE_ALLOW_UNSECURED_TRANSPORT=true +``` + +## [Windows](#tab/windows) + +```powershell +$env:ASPIRE_ALLOW_UNSECURED_TRANSPORT = "true" +``` + +Alternatively, you can control this via the launch profile. To do this, add the following setting to the `launchSettings.json` file, per transport setting: + +```json +{ + "$schema": "http://json.schemastore.org/launchsettings.json", + "profiles": { + "https": { + "commandName": "Project", + "dotnetRunMessages": true, + "launchBrowser": true, + "applicationUrl": "https://localhost:15015;http://localhost:15016", + "environmentVariables": { + "ASPNETCORE_ENVIRONMENT": "Development", + "DOTNET_ENVIRONMENT": "Development", + "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:16099", + "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:17037" + } + }, + "http": { + "commandName": "Project", + "dotnetRunMessages": true, + "launchBrowser": true, + "applicationUrl": "http://localhost:15016", + "environmentVariables": { + "ASPNETCORE_ENVIRONMENT": "Development", + "DOTNET_ENVIRONMENT": "Development", + "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:16099", + "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:17038", + "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true" + } + } + } +} +``` + +The preceding example shows two profiles, `https` and `http`. The `https` profile is configured with a secure transport protocol, while the `http` profile is configured with an insecure transport protocol. The `ASPIRE_ALLOW_UNSECURED_TRANSPORT` environment variable is set to `true` in the `http` profile to allow unsecure transport. From dd682d768941c1fab0ad6e5fa95df9f3a8004efb Mon Sep 17 00:00:00 2001 From: David Pine Date: Fri, 29 Mar 2024 10:25:38 -0500 Subject: [PATCH 2/4] fix tabs and correct text --- docs/troubleshooting/allow-unsecure-transport.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/troubleshooting/allow-unsecure-transport.md b/docs/troubleshooting/allow-unsecure-transport.md index 8965146861..e7591cbf9e 100644 --- a/docs/troubleshooting/allow-unsecure-transport.md +++ b/docs/troubleshooting/allow-unsecure-transport.md @@ -35,7 +35,9 @@ export ASPIRE_ALLOW_UNSECURED_TRANSPORT=true $env:ASPIRE_ALLOW_UNSECURED_TRANSPORT = "true" ``` -Alternatively, you can control this via the launch profile. To do this, add the following setting to the `launchSettings.json` file, per transport setting: +--- + +Alternatively, you can control this via the launch profile as it exposes the ability to configure environment variables per profile. To do this, consider the following example settings in the `launchSettings.json` file: ```json { From 5271cb2a05ba90a62e1cd4aa12e560443e7ad122 Mon Sep 17 00:00:00 2001 From: David Pine Date: Fri, 29 Mar 2024 10:26:06 -0500 Subject: [PATCH 3/4] Change from plaintext to output --- docs/troubleshooting/allow-unsecure-transport.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting/allow-unsecure-transport.md b/docs/troubleshooting/allow-unsecure-transport.md index e7591cbf9e..90eda76e30 100644 --- a/docs/troubleshooting/allow-unsecure-transport.md +++ b/docs/troubleshooting/allow-unsecure-transport.md @@ -12,7 +12,7 @@ Starting with .NET Aspire preview 5, the app host will crash if an `applicationU When you run a .NET Aspire application with an `applicationUrl` configured with an insecure transport protocol, you might see the following error message: -```plaintext +```Output The 'applicationUrl' setting must be an https address unless the 'ASPIRE_ALLOW_UNSECURED_TRANSPORT' environment variable is set to true. From 7650b6bf949b02affc3a8e5e67f8bb3a67eada36 Mon Sep 17 00:00:00 2001 From: David Pine Date: Fri, 29 Mar 2024 10:36:50 -0500 Subject: [PATCH 4/4] Change alert --- docs/deployment/manifest-format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deployment/manifest-format.md b/docs/deployment/manifest-format.md index 2c7f4f0ae2..e6de37225f 100644 --- a/docs/deployment/manifest-format.md +++ b/docs/deployment/manifest-format.md @@ -44,7 +44,7 @@ info: Aspire.Hosting.Publishing.ManifestPublisher[0] The file generated is the .NET Aspire manifest and is used by tools to support deploying into target cloud environments. -> [!TIP] +> [!NOTE] > You can also generate a manifest as part of the launch profile. Consider the following _launchSettings.json_: > > ```json