Skip to content

Commit 212a101

Browse files
IEvangelistCopilottdykstra
authored
Rewrite Azure Key Vault content (#2555)
* Fixes #2311 * Revert manifest tweaks * Update docs/snippets/azure/AppHost/Program.ConfigureKeyVaultInfra.cs Co-authored-by: Copilot <[email protected]> * Added hosting and client integration header bits * Fix build * Fix lasst link issue * Remove duplicate code block * Demote tips * Apply suggestions from code review Co-authored-by: Tom Dykstra <[email protected]> --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: Tom Dykstra <[email protected]>
1 parent 2aa3f21 commit 212a101

File tree

3 files changed

+367
-67
lines changed

3 files changed

+367
-67
lines changed

‎docs/database/includes/postgresql-flexible-server.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,3 +55,123 @@ The preceding call to `AddAzurePostgresFlexibleServer` configures the PostgresSQ
5555
5656
> [!TIP]
5757
> When you call <xref:Aspire.Hosting.AzurePostgresExtensions.AddAzurePostgresFlexibleServer*>, it implicitly calls <xref:Aspire.Hosting.AzureProvisionerExtensions.AddAzureProvisioning*>—which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](../../azure/local-provisioning.md#configuration).
58+
59+
#### Generated provisioning Bicep
60+
61+
If you're new to [Bicep](/azure/azure-resource-manager/bicep/overview), it's a domain-specific language for defining Azure resources. With .NET Aspire, you don't need to write Bicep by hand, because the provisioning APIs generate Bicep for you. When you publish your app, the generated Bicep is output alongside the manifest file. When you add an Azure PostgreSQL resource, the following Bicep is generated:
62+
63+
<!-- markdownlint-disable MD033 -->
64+
<br/>
65+
<details>
66+
<summary id="azure-postgresql"><strong>Toggle Azure PostgreSQL Bicep.</strong></summary>
67+
<p aria-labelledby="azure-postgresql">
68+
69+
:::code language="bicep" source="../../snippets/azure/AppHost/postgres-flexible.module.bicep":::
70+
71+
</p>
72+
</details>
73+
<!-- markdownlint-enable MD033 -->
74+
75+
The preceding Bicep is a module that provisions an Azure PostgreSQL flexible server with the following defaults:
76+
77+
- `authConfig`: The authentication configuration of the PostgreSQL server. The default is `ActiveDirectoryAuth` enabled and `PasswordAuth` disabled.
78+
- `availabilityZone`: The availability zone of the PostgreSQL server. The default is `1`.
79+
- `backup`: The backup configuration of the PostgreSQL server. The default is `BackupRetentionDays` set to `7` and `GeoRedundantBackup` set to `Disabled`.
80+
- `highAvailability`: The high availability configuration of the PostgreSQL server. The default is `Disabled`.
81+
- `storage`: The storage configuration of the PostgreSQL server. The default is `StorageSizeGB` set to `32`.
82+
- `version`: The version of the PostgreSQL server. The default is `16`.
83+
- `sku`: The SKU of the PostgreSQL server. The default is `Standard_B1ms`.
84+
- `tags`: The tags of the PostgreSQL server. The default is `aspire-resource-name` set to the name of the Aspire resource, in this case `postgres-flexible`.
85+
86+
In addition to the PostgreSQL flexible server, it also provisions an Azure Firewall rule to allow all Azure IP addresses. Finally, an administrator is created for the PostgreSQL server, and the connection string is outputted as an output variable. The generated Bicep is a starting point and can be customized to meet your specific requirements.
87+
88+
#### Customize provisioning infrastructure
89+
90+
All .NET Aspire Azure resources are subclasses of the <xref:Aspire.Hosting.Azure.AzureProvisioningResource> type. This type enables the customization of the generated Bicep by providing a fluent API to configure the Azure resources by using the <xref:Aspire.Hosting.AzureProvisioningResourceExtensions.ConfigureInfrastructure``1(Aspire.Hosting.ApplicationModel.IResourceBuilder{``0},System.Action{Aspire.Hosting.Azure.AzureResourceInfrastructure})> API. For example, you can configure the `kind`, `consistencyPolicy`, `locations`, and more. The following example demonstrates how to customize the PostgreSQL server resource:
91+
92+
:::code language="csharp" source="../../snippets/azure/AppHost/Program.ConfigurePostgresSQLInfra.cs" id="configure":::
93+
94+
The preceding code:
95+
96+
- Chains a call to the <xref:Aspire.Hosting.AzureProvisioningResourceExtensions.ConfigureInfrastructure*> API:
97+
- The `infra` parameter is an instance of the <xref:Aspire.Hosting.Azure.AzureResourceInfrastructure> type.
98+
- The provisionable resources are retrieved by calling the <xref:Azure.Provisioning.Infrastructure.GetProvisionableResources> method.
99+
- The single <xref:Azure.Provisioning.PostgreSql.PostgreSqlFlexibleServer> is retrieved.
100+
- The `sku` is set with <xref:Azure.Provisioning.PostgreSql.PostgreSqlFlexibleServerSkuTier.Burstable?displayProperty=nameWithType>.
101+
- The high availability properties are set with <xref:Azure.Provisioning.PostgreSql.PostgreSqlFlexibleServerHighAvailabilityMode.ZoneRedundant?displayProperty=nameWithType> in standby availability zone `"2"`.
102+
- A tag is added to the flexible server with a key of `ExampleKey` and a value of `Example value`.
103+
104+
There are many more configuration options available to customize the PostgreSQL flexible server resource. For more information, see <xref:Azure.Provisioning.PostgreSql> and [Azure.Provisioning customization](../../azure/integrations-overview.md#azureprovisioning-customization).
105+
106+
### Connect to an existing Azure PostgreSQL flexible server
107+
108+
You might have an existing Azure PostgreSQL flexible server that you want to connect to. Instead of representing a new Azure PostgreSQL flexible server resource, you can add a connection string to the app host. To add a connection to an existing Azure PostgreSQL flexible server, call the <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString*> method:
109+
110+
```csharp
111+
var builder = DistributedApplication.CreateBuilder(args);
112+
113+
var postgres = builder.AddConnectionString("postgres");
114+
115+
builder.AddProject<Projects.WebApplication>("web")
116+
.WithReference(postgres);
117+
118+
// After adding all resources, run the app...
119+
```
120+
121+
[!INCLUDE [connection-strings-alert](../../includes/connection-strings-alert.md)]
122+
123+
The connection string is configured in the app host's configuration, typically under [User Secrets](/aspnet/core/security/app-secrets), under the `ConnectionStrings` section. The app host injects this connection string as an environment variable into all dependent resources, for example:
124+
125+
```json
126+
{
127+
"ConnectionStrings": {
128+
"postgres": "Server=<PostgreSQL-server-name>.postgres.database.azure.com;Database=<database-name>;Port=5432;Ssl Mode=Require;User Id=<username>;"
129+
}
130+
}
131+
```
132+
133+
The dependent resource can access the injected connection string by calling the <xref:Microsoft.Extensions.Configuration.ConfigurationExtensions.GetConnectionString*> method, and passing the connection name as the parameter, in this case `"postgres"`. The `GetConnectionString` API is shorthand for `IConfiguration.GetSection("ConnectionStrings")[name]`.
134+
135+
### Run Azure PostgreSQL resource as a container
136+
137+
The Azure PostgreSQL hosting integration supports running the PostgreSQL server as a local container. This is beneficial for situations where you want to run the PostgreSQL server locally for development and testing purposes, avoiding the need to provision an Azure resource or connect to an existing Azure PostgreSQL server.
138+
139+
To run the PostgreSQL server as a container, call the <xref:Aspire.Hosting.AzurePostgresExtensions.RunAsContainer*> method:
140+
141+
```csharp
142+
var builder = DistributedApplication.CreateBuilder(args);
143+
144+
var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
145+
.RunAsContainer();
146+
147+
var postgresdb = postgres.AddDatabase("postgresdb");
148+
149+
var exampleProject = builder.AddProject<Projects.ExampleProject>()
150+
.WithReference(postgresdb);
151+
```
152+
153+
The preceding code configures an Azure PostgreSQL Flexible Server resource to run locally in a container.
154+
155+
> [!TIP]
156+
> The `RunAsContainer` method is useful for local development and testing. The API exposes an optional delegate that enables you to customize the underlying <xref:Aspire.Hosting.ApplicationModel.PostgresServerResource> configuration. For example, you can add pgAdmin and pgWeb, add a data volume or data bind mount, and add an init bind mount. For more information, see the [.NET Aspire PostgreSQL hosting integration](../postgresql-integration.md#add-postgresql-pgadmin-resource) section.
157+
158+
### Configure the Azure PostgreSQL server to use password authentication
159+
160+
By default, the Azure PostgreSQL server is configured to use [Microsoft Entra ID](/azure/postgresql/flexible-server/concepts-azure-ad-authentication) authentication. If you want to use password authentication, you can configure the server to use password authentication by calling the <xref:Aspire.Hosting.AzurePostgresExtensions.WithPasswordAuthentication*> method:
161+
162+
```csharp
163+
var builder = DistributedApplication.CreateBuilder(args);
164+
165+
var username = builder.AddParameter("username", secret: true);
166+
var password = builder.AddParameter("password", secret: true);
167+
168+
var postgres = builder.AddAzurePostgresFlexibleServer("postgres")
169+
.WithPasswordAuthentication(username, password);
170+
171+
var postgresdb = postgres.AddDatabase("postgresdb");
172+
173+
var exampleProject = builder.AddProject<Projects.ExampleProject>()
174+
.WithReference(postgresdb);
175+
```
176+
177+
The preceding code configures the Azure PostgreSQL server to use password authentication. The `username` and `password` parameters are added to the app host as parameters, and the `WithPasswordAuthentication` method is called to configure the Azure PostgreSQL server to use password authentication. For more information, see [External parameters](../../fundamentals/external-parameters.md).

0 commit comments

Comments
 (0)