compose: explicit mapping

[weikanglim]

Prelude

1. This issue is under proposal, and has not yet been committed into plans.
2. This issue may require additional design around the "object model" of resources since it introduces concepts like ${event-hubs-prod.name}. The design around the object model would be a separate scoped item. This object model may also be required as AVM modules also expose intermediate types that are not the underlying ARM types.

Explicit mapping

Overview

Explicit mapping is an intermediate/advanced feature that extends the current uses functionality. In contrast, to uses, which automatically injects environment variables into host resources based on standard naming conventions, explicit mapping does this explicitly.

Explicit mapping allows explicit association of resource properties (a higher-level object model) with environment variables, which is helpful in multi-dependency scenarios. The uses relationship is automatically derived from this mapping.

Example Mapping

resources:
  event-hubs-prod:
    type: messaging.eventhubs
  my-app:
    type: host.containerapp
    env:
      PRIMARY_EVENT_HUBS_NAME: ${event-hubs-prod.name}

This mapping explicitly assigns PRIMARY_EVENT_HUBS_NAME to the name of event-hubs-prod.

Scenario: Handling Multiple Dependencies

When a resource has multiple dependencies of the same type, automatic environment variable injection can cause ambiguity.

Problem

resources:
  event-hubs-prod:
    type: messaging.eventhubs
  event-hubs-dev:
    type: messaging.eventhubs
  my-app:
    type: compute.containerapp
    uses:
      - event-hubs-prod
      - event-hubs-dev
    # This would auto-inject environment variables but become ambiguous
    # Which event hub does AZURE_EVENT_HUBS_NAME refer to?

Proposed Solution

To remove ambiguity, explicit environment variable mapping is used:

resources:
  event-hubs-prod:
    type: messaging.eventhubs
  event-hubs-dev:
    type: messaging.eventhubs
  my-app:
    type: compute.containerapp
    env:
      PRIMARY_EVENT_HUBS_NAME: ${event-hubs-prod.name}
      SECONDARY_EVENT_HUBS_NAME: ${event-hubs-dev.name}

Proposed Implementation

The add command will generate default environment variable mappings when adding a second dependency of the same type. Users can override these mappings explicitly to provide meaningful names.

[JeffreyCA]

Do you see scenarios where azure.yml with explicit uses: is still used? Or is this something that would replace uses:?

Would this also affect azd init?

[weikanglim]

I think we want uses to be a standard -- because standards are useful. Having standard environment variables reduces the barrier of entry and mental cognitive load. The developer just needs to grab the variables as-is without thinking too much when building up an application.

For example, this could be used as part of #4727 with azd show service-bus.env to show the standard environment variables to connect to it.

Would this also affect azd init?

Possibly. I do think of azd init as a series of azd add over time.