compose: resource conventions

[weikanglim]

!! WIP: Work in progress. This is a draft and does not represent final work.

General Conventions

1. Type Naming:

   • Resource types are written without hyphens.
   • Example: messaging.eventhubs instead of messaging-eventhubs.

2. Default Resource Naming (simplified scaffolding scenarios):

   • When adding a resource using azd add, a single resource is created with a default name.
   • Example:
     • event-hubs for messaging.eventhubs.
     • The default name follows a hyphenated format.

3. Environment Variables:

   • Environment variables follow the format: AZURE_<TYPE>_<PROPERTY>. Unlike the type referenced in 1, underscores may be part of the name for variable naming clarity.
   • With messaging.eventhubs which stems from "Azure Event Hubs", AZURE_EVENT_HUBS_NAME represents the Event Hubs namespace.
   • When there are more than one types, an explicit environment variable mapping must be performed (which azd add can provide a default configuration modification that is used).

Common Properties

Suffix	Description
_HOST	Hostname, i.e. myaccount.blob.core.windows.net
_URL	URI reference , i.e. redis://
_ENDPOINT	HTTP URL , i.e. https://<vault-name>.vault.azure.net/
_PORT	Port number, i.e. 333

Resource Definitions

Event Hubs

YAML Definition

resources:
  event-hubs:
    type: messaging.eventhubs
    hubs:
      - events

Binding Environment Variables

Variable	Description
AZURE_EVENT_HUBS_NAME	Name of the Event Hubs namespace
AZURE_EVENT_HUBS_HOST	Hostname of the Event Hubs namespace

---

Service Bus

YAML Definition

resources:
  service-bus:
    type: messaging.servicebus
    queues:
      - myQueue
    topics:
      - myTopic

Binding Environment Variables

Variable	Description
AZURE_SERVICE_BUS_NAME	Name of the Service Bus namespace
AZURE_SERVICE_BUS_HOST	Hostname of the Service Bus namespace

---

[JeffreyCA]

Environment variables follow the format: AZURE_<TYPE>_<PROPERTY>.

Given Convention 1, should <TYPE> here not contain any underscores? Do we expect to be able to parse out <TYPE> and <PROPERTY> from an environment variable name? Just wondering if there could be some ambiguity if both the type and property contain underscores.

[weikanglim]

Given Convention 1, should here not contain any underscores

There's definitely a point of confusion here, the environment variable naming should be stemmed from the official Azure resource naming.

I did made an explicit decision with this initial draft to have Types shortened for brevity and look closer to general programming language types, but for Environment variables to follow better standard environment variable naming conventions for clarity. I have updated the draft slightly to reflect this decision. Feel free to have a chat open for any thoughts here.

Do we expect to be able to parse out and from an environment variable name

This is a good point. In general, I don't believe this is done in practice -- the variables are just standard conventional environment variables of ALPHA_UPPER_SNAKE_CASE. The convention is to facilitate us leaning towards a standard practice, but we have no guarantees over machine operability. In areas of contention, I would lean towards favoring human readability here over machine operability.

[rujche]

About the resource conventions, I think it's a part of azure.yaml schema.

I have a draft design about Deploy project to Azure by azure.yaml. The azure.yaml are used by multiple tools, including azd, SJAD project analyzer, code-to-cloud, maybe the future, we will have other tools like: IDE plugins, other project analyzers like (.NET project analyzer, js project analyzer).

In my draft design, we should move the schema definition out of azd, so all tools can follow the same schema. We can follow this flow:

1. Define / update azure-dot-yaml-schema, release a new version of azure-dot-yaml-schema.
2. All teams update their tool to support new version of azure-dot-yaml-schema. Each team self should care about the compatibility by themselves.
3. One tool generated azure.yaml can be consumed (merged) by another tool.

Back to current issue, the discussion about resource conversion should move to the azure-dot-yaml-schama discussion.

[rujche]

When define common properties, this list can provide more candidates:

https://github.com/Azure/azure-dev/pull/4473/files

[rujche]

About Type Naming, it's possible that customer has existing resources which are not belong to azure. To satisfy this requirement, we can add azure to type name. For example: change messaging.eventhubs to azure.messaging.eventhubs.