Document WithRealmImport production limitation and alternatives

src/frontend/src/content/docs/integrations/security/keycloak.mdx

@@ -190,7 +190,7 @@ await builder.build().run();
 <Aside>
   Data bind mounts have limited functionality compared to volumes, and when you
   use a bind mount, a file or directory on the host machine is mounted into a
-  container.
+  container. Bind mounts are best suited to local development and testing.
 </Aside>
 
 ### Add Keycloak resource with parameters
@@ -273,7 +273,106 @@ await builder.build().run();
 </TabItem>
 </Tabs>
 
-The realm import files are mounted at `/opt/keycloak/data/import` in the Keycloak container. Realm import files are JSON files that represent the realm configuration.
+The realm import files are copied to `/opt/keycloak/data/import` in the
+Keycloak container. Realm import files are JSON files that represent the realm
+configuration.
+
+<Aside type="caution">
+  `WithRealmImport` is intended for local development. It uses development-time
+  container file injection and isn't supported when publishing or deploying the
+  AppHost with `aspire publish` or `aspire deploy`. For production deployments,
+  bake realm files into a custom image or seed Keycloak from an initialization
+  process. This is the current behavior for the Keycloak integration; check the
+  release notes for future changes.
+</Aside>
+
+#### Production alternatives for realm seeding
+
+For production environments, consider these alternatives to seed your Keycloak
+instance:
+
+**Custom Keycloak image**: Bake realm files into a custom image. Apply
+`WithDockerfile` to the Keycloak resource instead of replacing `AddKeycloak`
+with `AddContainer`:
+
+```dockerfile title="keycloak/Dockerfile"
+FROM quay.io/keycloak/keycloak:25.0.0
+COPY ./realms/*.json /opt/keycloak/data/import/
+```
+
+<Tabs syncKey='aspire-lang'>
+<TabItem id='csharp' label='C#'>
+```csharp title="AppHost.cs"
+var builder = DistributedApplication.CreateBuilder(args);
+
+var keycloak = builder.AddKeycloak("keycloak", 8080)
+    .WithDockerfile("./keycloak");
+
+var apiService = builder.AddProject<Projects.ApiService>("apiservice")
+    .WithReference(keycloak)
+    .WaitFor(keycloak);
+
+builder.Build().Run();
+```
+</TabItem>
+<TabItem id='typescript' label='TypeScript'>
+```typescript title="apphost.mts"
+import { createBuilder } from './.aspire/modules/aspire.mjs';
+
+const builder = await createBuilder();
+
+const keycloak = await builder.addKeycloak("keycloak", 8080);
+await keycloak.withDockerfile("./keycloak");
+
+const apiService = await builder.addProject("apiservice", "../ApiService/ApiService.csproj");
+await apiService.withReference(keycloak);
+await apiService.waitFor(keycloak);
+
+await builder.build().run();
+```
+</TabItem>
+</Tabs>
+
+<Tabs syncKey='aspire-lang'>
+<TabItem id='csharp' label='C#'>
+
+```text title="Directory layout"
+AppHost.cs
+keycloak/
+  Dockerfile
+  realms/
+    demo-realm.json
+```
+
+</TabItem>
+<TabItem id='typescript' label='TypeScript'>
+
+```text title="Directory layout"
+apphost.mts
+keycloak/
+  Dockerfile
+  realms/
+    demo-realm.json
+```
+
+</TabItem>
+</Tabs>
+
+<Aside type="tip">
+  This approach keeps the defaults that `AddKeycloak` applies, including the
+  Keycloak startup arguments. You don't need an extra `WithArgs("start",
+  "--import-realm")` call when you keep using `AddKeycloak`.
+</Aside>
+
+**Initialization service**: Create a separate initialization service or job
+that uses the [Keycloak Admin REST API](https://www.keycloak.org/docs-api/latest/rest-api/index.html)
+or [Keycloak Admin Client](https://www.nuget.org/packages/Keycloak.AuthServices.Sdk.Admin)
+to create and configure realms, clients, and users when the Keycloak instance
+first starts.
+
+**Infrastructure as Code**: Use tools like Terraform with the
+[Keycloak provider](https://registry.terraform.io/providers/mrparkers/keycloak/latest/docs)
+to manage realm configuration separately from your application deployment.
 
 ### Export telemetry to <abbr title="OpenTelemetry Protocol" data-tooltip-placement="top">OTLP</abbr> collector
 
@@ -316,7 +415,8 @@ This enables Keycloak to send traces, metrics, and logs to the Aspire dashboard,
 
 ### Hosting integration health checks
 
-The Keycloak hosting integration doesn't currently support health checks, nor does it automatically add them.
+The Keycloak hosting integration automatically adds an HTTP health check
+against the management endpoint's `/health/ready` path.
 
 ## Client integration