@intentius/chant-lexicon-azure 0.124.38 → 0.124.40

package/src/composites/composites.test.ts

@@ -14,6 +14,7 @@ import { ApplicationGateway } from "./application-gateway";
 import { ContainerInstance } from "./container-instance";
 import { RedisCache } from "./redis-cache";
 import { PrivateEndpoint } from "./private-endpoint";
+import { ContainerAppNetwork, ContainerAppSite } from "./container-app";
 import { isCompositeInstance } from "@intentius/chant";
 
 /** Helper to get flat props from a generated resource instance. */
@@ -744,3 +745,130 @@ describe("PrivateEndpoint", () => {
     expect(peTags["managed-by"]).toBe("chant");
   });
 });
+
+// --- ContainerAppNetwork ---
+
+describe("ContainerAppNetwork", () => {
+  test("returns a VNet and its subnet", () => {
+    const result = ContainerAppNetwork({ name: "web" });
+    expect(Object.keys(result.members)).toEqual(["virtualNetwork", "subnet"]);
+    expect(et(result.virtualNetwork)).toBe("Microsoft.Network/virtualNetworks");
+    expect(et(result.subnet)).toBe("Microsoft.Network/virtualNetworks_subnets");
+  });
+
+  test("names the subnet as a child of <name>-vnet and delegates it to Container Apps", () => {
+    const { virtualNetwork, subnet } = ContainerAppNetwork({ name: "web", subnetPrefix: "10.1.0.0/23" });
+    expect(p(virtualNetwork).name).toBe("web-vnet");
+    expect(p(subnet).name).toBe("web-vnet/apps");
+    expect(p(subnet).addressPrefix).toBe("10.1.0.0/23");
+    const delegations = p(subnet).delegations as Array<{ properties: { serviceName: string } }>;
+    expect(delegations[0].properties.serviceName).toBe("Microsoft.App/environments");
+  });
+
+  test("lists the subnet inline on the VNet too", () => {
+    const { virtualNetwork } = ContainerAppNetwork({ name: "web" });
+    const subnets = p(virtualNetwork).subnets as Array<{ name: string; properties: { addressPrefix: string } }>;
+    expect(subnets).toHaveLength(1);
+    expect(subnets[0].name).toBe("apps");
+    expect(subnets[0].properties.addressPrefix).toBe("10.0.0.0/23");
+  });
+
+  test("defaults override a member's props", () => {
+    const { virtualNetwork } = ContainerAppNetwork({ name: "web", defaults: { virtualNetwork: { location: "westeurope" } } });
+    expect(p(virtualNetwork).location).toBe("westeurope");
+  });
+
+  type Inline = { name: string; properties: Record<string, unknown> };
+
+  test("defaults.subnet reaches the inline entry as well as the Subnet resource", () => {
+    const nsg = { id: "[resourceId('Microsoft.Network/networkSecurityGroups', 'web-nsg')]" };
+    const routeTable = { id: "[resourceId('Microsoft.Network/routeTables', 'web-rt')]" };
+    const { virtualNetwork, subnet } = ContainerAppNetwork({
+      name: "web",
+      defaults: { subnet: { networkSecurityGroup: nsg, routeTable } as any },
+    });
+    const inline = (p(virtualNetwork).subnets as Inline[])[0];
+    expect(p(subnet).networkSecurityGroup).toEqual(nsg);
+    expect(inline.properties.networkSecurityGroup).toEqual(nsg);
+    expect(inline.properties.routeTable).toEqual(routeTable);
+    const { name: _n, ...flat } = p(subnet);
+    expect(inline.properties).toEqual(flat);
+  });
+
+  test("defaults.virtualNetwork.subnets adds subnets after apps and keeps its delegation", () => {
+    const { virtualNetwork } = ContainerAppNetwork({
+      name: "web",
+      defaults: { virtualNetwork: { subnets: [{ name: "db", properties: { addressPrefix: "10.0.2.0/24" } }] } as any },
+    });
+    const subnets = p(virtualNetwork).subnets as Inline[];
+    expect(subnets.map((s) => s.name)).toEqual(["apps", "db"]);
+    const delegations = subnets[0].properties.delegations as Array<{ properties: { serviceName: string } }>;
+    expect(delegations[0].properties.serviceName).toBe("Microsoft.App/environments");
+  });
+
+  test("a caller's own apps entry in defaults.virtualNetwork.subnets is replaced by the merged one", () => {
+    const { virtualNetwork } = ContainerAppNetwork({
+      name: "web",
+      defaults: { virtualNetwork: { subnets: [{ name: "apps", properties: { addressPrefix: "10.9.0.0/23" } }] } as any },
+    });
+    const subnets = p(virtualNetwork).subnets as Inline[];
+    expect(subnets).toHaveLength(1);
+    expect(subnets[0].properties.addressPrefix).toBe("10.0.0.0/23");
+    expect(subnets[0].properties.delegations).toBeDefined();
+  });
+});
+
+// --- ContainerAppSite ---
+
+describe("ContainerAppSite", () => {
+  const subnetId = "[resourceId('Microsoft.Network/virtualNetworks/subnets', 'web-vnet', 'apps')]";
+
+  test("returns a workspace, identity, environment and app", () => {
+    const result = ContainerAppSite({ name: "web", app: "frontend", subnetId });
+    expect(Object.keys(result.members)).toEqual(["workspace", "identity", "environment", "containerApp"]);
+    expect(et(result.workspace)).toBe("Microsoft.OperationalInsights/workspaces");
+    expect(et(result.identity)).toBe("Microsoft.ManagedIdentity/userAssignedIdentities");
+    expect(et(result.environment)).toBe("Microsoft.App/managedEnvironments");
+    expect(et(result.containerApp)).toBe("Microsoft.App/containerApps");
+  });
+
+  test("puts the environment in the subnet on the Consumption profile, logging to the workspace", () => {
+    const { workspace, environment } = ContainerAppSite({ name: "web", app: "frontend", subnetId });
+    expect(p(workspace).name).toBe("web-logs");
+    const env = p(environment);
+    expect(env.vnetConfiguration).toEqual({ infrastructureSubnetId: subnetId, internal: false });
+    expect(env.workloadProfiles).toEqual([{ name: "Consumption", workloadProfileType: "Consumption" }]);
+    const logs = (env.appLogsConfiguration as { logAnalyticsConfiguration: Record<string, string> }).logAnalyticsConfiguration;
+    expect(logs.customerId).toContain("reference(resourceId('Microsoft.OperationalInsights/workspaces', 'web-logs')");
+    expect(logs.sharedKey).toContain("listKeys(resourceId('Microsoft.OperationalInsights/workspaces', 'web-logs')");
+  });
+
+  test("runs the app as the identity behind external ingress", () => {
+    const { identity, containerApp } = ContainerAppSite({ name: "web", app: "frontend", subnetId, image: "nginx:1.27", port: 8080, replicas: 2 });
+    expect(p(identity).name).toBe("web-frontend");
+    const app = p(containerApp);
+    expect(app.name).toBe("frontend");
+    const ids = (app.identity as { userAssignedIdentities: Record<string, unknown> }).userAssignedIdentities;
+    expect(Object.keys(ids)).toEqual(["[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', 'web-frontend')]"]);
+    expect(app.configuration).toEqual({ ingress: { external: true, targetPort: 8080, transport: "auto" } });
+    const template = app.template as { containers: Array<{ image: string }>; scale: Record<string, number> };
+    expect(template.containers[0].image).toBe("nginx:1.27");
+    expect(template.scale).toEqual({ minReplicas: 2, maxReplicas: 2 });
+  });
+
+  test("internal makes the environment VNet-only", () => {
+    const { environment } = ContainerAppSite({ name: "web", app: "frontend", subnetId, internal: true });
+    expect((p(environment).vnetConfiguration as Record<string, unknown>).internal).toBe(true);
+  });
+
+  test("defaults override a member's props", () => {
+    const { workspace } = ContainerAppSite({ name: "web", app: "frontend", subnetId, defaults: { workspace: { retentionInDays: 90 } } });
+    expect(p(workspace).retentionInDays).toBe(90);
+  });
+
+  test("takes a ContainerAppNetwork's subnet id", () => {
+    const network = ContainerAppNetwork({ name: "web" });
+    const { environment } = ContainerAppSite({ name: "web", app: "frontend", subnetId: network.subnet.id });
+    expect((p(environment).vnetConfiguration as Record<string, unknown>).infrastructureSubnetId).toBe(network.subnet.id);
+  });
+});

package/src/composites/container-app.ts

@@ -0,0 +1,230 @@
+/**
+ * ContainerAppNetwork and ContainerAppSite composites: a website on Azure
+ * Container Apps and the network it sits in.
+ *
+ * Split the way the aws lexicon splits VpcDefault from FargateAlb, so several
+ * sites can share one network. Container Apps brings its own ingress and load
+ * balancing, so there is no load balancer to declare.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import {
+  VirtualNetwork,
+  Subnet,
+  LogAnalyticsWorkspace,
+  ManagedIdentity,
+  managedEnvironments,
+  containerApps,
+} from "../generated";
+
+export interface ContainerAppNetworkProps {
+  /** Network name prefix: the VNet is `<name>-vnet`, its subnet `apps`. */
+  name: string;
+  /** Azure region (default: resource group location). */
+  location?: string;
+  /** VNet address space (default: "10.0.0.0/16"). */
+  addressSpace?: string;
+  /** The environment subnet's prefix, a /23 or larger (default: "10.0.0.0/23"). */
+  subnetPrefix?: string;
+  /** Resource tags. */
+  tags?: Record<string, string>;
+  /** Per-member defaults. */
+  defaults?: {
+    virtualNetwork?: Partial<ConstructorParameters<typeof VirtualNetwork>[0]>;
+    subnet?: Partial<ConstructorParameters<typeof Subnet>[0]>;
+  };
+}
+
+export interface ContainerAppNetworkResult {
+  virtualNetwork: InstanceType<typeof VirtualNetwork>;
+  subnet: InstanceType<typeof Subnet>;
+}
+
+/**
+ * A VNet with a subnet delegated to `Microsoft.App/environments`, for
+ * ContainerAppSite environments to sit in.
+ *
+ * @example
+ * ```ts
+ * import { ContainerAppNetwork } from "@intentius/chant-lexicon-azure";
+ *
+ * export const network = ContainerAppNetwork({ name: "web" });
+ * ```
+ */
+export const ContainerAppNetwork = Composite((props: ContainerAppNetworkProps) => {
+  const {
+    name,
+    location = "[resourceGroup().location]",
+    addressSpace = "10.0.0.0/16",
+    subnetPrefix = "10.0.0.0/23",
+    tags = {},
+    defaults,
+  } = props;
+
+  const mergedTags = { "managed-by": "chant", ...tags };
+  const vnetName = `${name}-vnet`;
+  const delegations = [{ name: "apps", properties: { serviceName: "Microsoft.App/environments" } }];
+
+  const subnet = new Subnet(mergeDefaults({
+    name: `${vnetName}/apps`,
+    addressPrefix: subnetPrefix,
+    delegations,
+  }, defaults?.subnet), { apiVersion: "2023-05-01" });
+
+  // The subnet is also listed inline, as VnetDefault does, so a later
+  // deployment of the VNet does not try to remove it. The inline entry is
+  // built from the Subnet resource's merged props, so `defaults.subnet`
+  // reaches both copies. The apps entry always comes first; a caller's
+  // `defaults.virtualNetwork.subnets` adds the other subnets after it, and
+  // an entry of theirs named "apps" is replaced by this one.
+  const { subnets: extraSubnets, ...vnetDefaults } = (defaults?.virtualNetwork ?? {}) as {
+    subnets?: Array<{ name?: string }>;
+  } & Record<string, unknown>;
+  const virtualNetwork = new VirtualNetwork(mergeDefaults({
+    name: vnetName,
+    location,
+    tags: mergedTags,
+    addressSpace: { addressPrefixes: [addressSpace] },
+    subnets: [
+      inlineSubnet("apps", subnetProps(subnet)),
+      ...(extraSubnets ?? []).filter((s) => s?.name !== "apps"),
+    ],
+  }, vnetDefaults), { apiVersion: "2023-05-01" });
+
+  return { virtualNetwork, subnet };
+}, "ContainerAppNetwork");
+
+/** A Subnet resource's props, flat or under `properties`. */
+function subnetProps(subnet: InstanceType<typeof Subnet>): Record<string, unknown> {
+  return (subnet as unknown as { props: Record<string, unknown> }).props;
+}
+
+/** The VNet's inline entry for a subnet, from that Subnet resource's props. */
+function inlineSubnet(name: string, props: Record<string, unknown>) {
+  const { name: _name, id: _id, properties, ...flat } = props;
+  return { name, properties: { ...flat, ...(properties as Record<string, unknown> | undefined) } };
+}
+
+export interface ContainerAppSiteProps {
+  /** Environment name; the workspace is `<name>-logs` and the identity `<name>-<app>`. */
+  name: string;
+  /** Container app name. */
+  app: string;
+  /** Subnet resource ID for the environment, such as a ContainerAppNetwork's `subnet.id`. */
+  subnetId: string;
+  /** Azure region (default: resource group location). */
+  location?: string;
+  /** Container image (default: "mcr.microsoft.com/k8se/quickstart:latest"). */
+  image?: string;
+  /** Port the container listens on; ingress forwards to it (default: 80). */
+  port?: number;
+  /** Fixed replica count (default: 1). */
+  replicas?: number;
+  /** Make the environment reachable only from its VNet (default: false). */
+  internal?: boolean;
+  /** Resource tags. */
+  tags?: Record<string, string>;
+  /** Per-member defaults. */
+  defaults?: {
+    workspace?: Partial<ConstructorParameters<typeof LogAnalyticsWorkspace>[0]>;
+    identity?: Partial<ConstructorParameters<typeof ManagedIdentity>[0]>;
+    environment?: Partial<ConstructorParameters<typeof managedEnvironments>[0]>;
+    containerApp?: Partial<ConstructorParameters<typeof containerApps>[0]>;
+  };
+}
+
+export interface ContainerAppSiteResult {
+  workspace: InstanceType<typeof LogAnalyticsWorkspace>;
+  identity: InstanceType<typeof ManagedIdentity>;
+  environment: InstanceType<typeof managedEnvironments>;
+  containerApp: InstanceType<typeof containerApps>;
+}
+
+/**
+ * A Container Apps environment in a subnet, shipping logs to its own Log
+ * Analytics workspace, with one app running as a user-assigned identity.
+ *
+ * @example
+ * ```ts
+ * import { ContainerAppNetwork, ContainerAppSite } from "@intentius/chant-lexicon-azure";
+ *
+ * export const network = ContainerAppNetwork({ name: "web" });
+ * export const site = ContainerAppSite({
+ *   name: "web",
+ *   app: "frontend",
+ *   subnetId: network.subnet.id,
+ *   image: "nginx:1.27",
+ * });
+ * ```
+ */
+export const ContainerAppSite = Composite((props: ContainerAppSiteProps) => {
+  const {
+    name,
+    app,
+    subnetId,
+    location = "[resourceGroup().location]",
+    image = "mcr.microsoft.com/k8se/quickstart:latest",
+    port = 80,
+    replicas = 1,
+    internal = false,
+    tags = {},
+    defaults,
+  } = props;
+
+  const mergedTags = { "managed-by": "chant", ...tags };
+  const workspaceName = `${name}-logs`;
+  const identityName = `${name}-${app}`;
+  const workspaceId = `resourceId('Microsoft.OperationalInsights/workspaces', '${workspaceName}')`;
+
+  const workspace = new LogAnalyticsWorkspace(mergeDefaults({
+    name: workspaceName,
+    location,
+    tags: mergedTags,
+    // A workspace's sku sits inside its properties, not beside them, so it is
+    // passed there rather than hoisted to the resource like other skus.
+    properties: { sku: { name: "PerGB2018" } },
+    retentionInDays: 30,
+  }, defaults?.workspace), { apiVersion: "2023-09-01" });
+
+  const identity = new ManagedIdentity(mergeDefaults({
+    name: identityName,
+    location,
+    tags: mergedTags,
+  }, defaults?.identity), { apiVersion: "2023-01-31" });
+
+  const environment = new managedEnvironments(mergeDefaults({
+    name,
+    location,
+    tags: mergedTags,
+    vnetConfiguration: { infrastructureSubnetId: subnetId, internal },
+    appLogsConfiguration: {
+      destination: "log-analytics",
+      logAnalyticsConfiguration: {
+        customerId: `[reference(${workspaceId}, '2023-09-01').customerId]`,
+        sharedKey: `[listKeys(${workspaceId}, '2023-09-01').primarySharedKey]`,
+      },
+    },
+    workloadProfiles: [{ name: "Consumption", workloadProfileType: "Consumption" }],
+  }, defaults?.environment), { apiVersion: "2024-03-01" });
+
+  const containerApp = new containerApps(mergeDefaults({
+    name: app,
+    location,
+    tags: mergedTags,
+    identity: {
+      type: "UserAssigned",
+      userAssignedIdentities: {
+        [`[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', '${identityName}')]`]: {},
+      },
+    },
+    managedEnvironmentId: environment.id,
+    workloadProfileName: "Consumption",
+    configuration: { ingress: { external: true, targetPort: port, transport: "auto" } },
+    template: {
+      containers: [{ name: app, image, resources: { cpu: 0.25, memory: "0.5Gi" } }],
+      scale: { minReplicas: replicas, maxReplicas: replicas },
+    },
+  }, defaults?.containerApp), { apiVersion: "2024-03-01" });
+
+  return { workspace, identity, environment, containerApp };
+}, "ContainerAppSite");

package/src/composites/index.ts

@@ -28,6 +28,11 @@ export { RedisCache } from "./redis-cache";
 export type { RedisCacheProps, RedisCacheResult } from "./redis-cache";
 export { PrivateEndpoint } from "./private-endpoint";
 export type { PrivateEndpointProps, PrivateEndpointResult } from "./private-endpoint";
+export { ContainerAppNetwork, ContainerAppSite } from "./container-app";
+export type {
+  ContainerAppNetworkProps, ContainerAppNetworkResult,
+  ContainerAppSiteProps, ContainerAppSiteResult,
+} from "./container-app";
 export { GovernanceFoundation, GovernanceBaseline, LocationRestriction, ActivityLogSink } from "./landing-zone";
 export type {
   GovernanceFoundationProps, GovernanceFoundationResult,

package/src/deep-observe.ts

@@ -67,7 +67,7 @@ import { AZURE_TAG_OWNERSHIP_KEYS } from "./ownership";
 
 
 /** The full `az resource show -o json` shape this reader reads (a superset of the thin path's `AzResourceShowResponse`). */
-interface ArmResourceShowResponse {
+export interface ArmResourceShowResponse {
   id?: string;
   name?: string;
   type?: string;
@@ -96,7 +96,7 @@ interface ArmResourceShowResponse {
  * returned 200 is the declared name. The leaf is folded back to the declared
  * spelling; a name that is not the leaf of the query is kept as returned.
  */
-function buildLiveProperties(obj: ArmResourceShowResponse, queriedName?: string): Record<string, unknown> {
+export function buildLiveProperties(obj: ArmResourceShowResponse, queriedName?: string): Record<string, unknown> {
   const out: Record<string, unknown> = {};
   if (obj.name !== undefined) {
     out.name =

package/src/index.ts

@@ -17,6 +17,9 @@ export { defaultTags, type TagEntry, type DefaultTags } from "./default-tags";
 export { deploymentScope, isDeploymentScope, type DeploymentScope, type DeployScope } from "./deploy-scopes";
 export { azureSerializer } from "./serializer";
 export { azurePlugin } from "./plugin";
+// Core's capability-plugin loader scans this package's exports and loads
+// `azureCapabilityPlugin` when a project's chant.config lists this lexicon (#4273).
+export { azureCapabilityPlugin } from "./components/capability-plugin";
 export { Parameter } from "./parameter";
 
 // Deep observation (#1086): the `az resource show` reader and the noise
@@ -78,6 +81,8 @@ export {
   ContainerInstance, type ContainerInstanceProps, type ContainerInstanceResult,
   RedisCache, type RedisCacheProps, type RedisCacheResult,
   PrivateEndpoint, type PrivateEndpointProps, type PrivateEndpointResult,
+  ContainerAppNetwork, type ContainerAppNetworkProps, type ContainerAppNetworkResult,
+  ContainerAppSite, type ContainerAppSiteProps, type ContainerAppSiteResult,
   GovernanceFoundation, type GovernanceFoundationProps, type GovernanceFoundationResult,
   GovernanceBaseline, type GovernanceBaselineProps, type GovernanceBaselineResult,
   LocationRestriction, type LocationRestrictionProps, type LocationRestrictionResult,

package/src/plugin.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect } from "vitest";
 import { azurePlugin } from "./plugin";
 import { isLexiconPlugin } from "@intentius/chant/lexicon";
+import { emulatorsOf, endpointEnvVars } from "@intentius/chant/op";
 
 describe("azurePlugin", () => {
   // -----------------------------------------------------------------------
@@ -233,3 +234,12 @@ describe("azurePlugin", () => {
     expect(ids).toContain("AZR011");
   });
 });
+
+// #4281: `chant components pr-plan`, `pr-apply` and `run --components` apply an
+// environment's declared endpoint to the vars the plugin's emulator names. `arm-deploy`
+// reads AZURE_ENDPOINT_URL, so the plugin has to name it.
+describe("azurePlugin endpoint var (#4281)", () => {
+  test("the emulator names AZURE_ENDPOINT_URL, the var arm-deploy reads", () => {
+    expect(emulatorsOf(azurePlugin.emulator).flatMap((cap) => endpointEnvVars(cap))).toEqual(["AZURE_ENDPOINT_URL"]);
+  });
+});

package/src/skills/chant-azure-patterns.md

@@ -408,6 +408,22 @@ const { privateEndpoint, privateDnsZone, dnsZoneGroup, vnetLink } = PrivateEndpo
 export { storageAccount, privateEndpoint, privateDnsZone, dnsZoneGroup, vnetLink };
 ```
 
+### ContainerAppNetwork and ContainerAppSite
+A Container Apps site in its own delegated subnet; one network can carry several sites:
+
+```ts
+import { ContainerAppNetwork, ContainerAppSite } from "@intentius/chant-lexicon-azure";
+
+export const network = ContainerAppNetwork({ name: "web" });
+
+export const site = ContainerAppSite({
+  name: "web",
+  app: "frontend",
+  subnetId: network.subnet.id,
+  image: "nginx:1.27",
+});
+```
+
 ## ARM Template Intrinsic Reference
 
 | Function | Description | Example |

package/src/skills/chant-azure-security.md

@@ -267,6 +267,7 @@ Use the secure composite variants which apply these patterns automatically:
 - `ContainerInstance` — Managed identity, no public IP by default
 - `RedisCache` — Non-SSL port disabled, TLS 1.2
 - `PrivateEndpoint` — Private connectivity pattern with DNS zone
+- `ContainerAppSite`: user-assigned identity, app logs to Log Analytics, optional VNet-only environment
 
 ## Post-Synth Check Reference
 

package/src/skills/chant-azure.md

@@ -157,6 +157,8 @@ Composites group related Azure resources with secure defaults. Each returns an o
 | `ContainerInstance` | ContainerGroup | No public IP by default, resource limits set |
 | `RedisCache` | RedisCache | TLS 1.2 required, non-SSL port disabled |
 | `PrivateEndpoint` | PrivateEndpoint + PrivateDnsZone + VnetLink | DNS zone auto-registration, manual approval disabled |
+| `ContainerAppNetwork` | VirtualNetwork + Subnet | Subnet delegated to Container Apps, /23 by default |
+| `ContainerAppSite` | LogAnalyticsWorkspace + ManagedIdentity + ManagedEnvironment + ContainerApp | App logs to Log Analytics, user-assigned identity, Consumption profile |
 | `AksCluster` | ManagedCluster + AgentPool | RBAC enabled, network policy (calico), managed identity, Azure CNI |
 | `SqlDatabase` | SQLServer + Database + FirewallRule + AuditingSettings | TDE enabled, auditing enabled, TLS 1.2, no Azure-wide firewall rule |
 | `KeyVaultSecure` | KeyVault + AccessPolicy | Soft delete, purge protection, RBAC authorization, network ACLs |