[resource-manager] How could we define a "tenant level" external resource?

[ArcturusZhang]

We want to define a resource whose id looks like this:

/providers/Microsoft.Management/serviceGroups/{servicegroupName}/providers/Microsoft.Edge/sites/{siteName}

and in this situation we have to use the legacy operations.

I noticed that we could define an external resource in this way:

alias ServiceGroup = Extension.ExternalResource<
  Extension.Tenant,
  "Microsoft.Management",
  "serviceGroups",
  "serviceGroupName",
  NamePattern = "^[a-zA-Z0-9\\-_().]{1,90}$",
  Description = "The name of the service group"
>;

and then I could use ResourceInstanceParameter<ServiceGroup> to get its parameters so that I do not need to define them one by one, and everything looks very organized, like this:

alias SiteByServiceGroupOps = Azure.ResourceManager.Legacy.ExtensionOperations<
  ResourceInstanceParameters<ServiceGroup>,
  Extension.ExtensionProviderNamespace<Site>,
  {
    ...Extension.ExtensionProviderNamespace<Site>;
    ...KeysOf<Site>;
  }
>;

@armResourceOperations(#{ omitTags: true })
interface SitesByServiceGroup {
  @doc("list Site at SG scope")
  @list
  listByServiceGroup is SiteByServiceGroupOps.List<Site>;

  @doc("Get Site at SG scope")
  get is SiteByServiceGroupOps.Read<Site>;

  @doc("create or update Site at SG scope")
  createOrUpdate is SiteByServiceGroupOps.CreateOrUpdateAsync<Site>;

  @doc("update Site at SG scope")
  @patch(#{ implicitOptionality: true })
  update is SiteByServiceGroupOps.CustomPatchSync<Site, SiteUpdate>;

  @doc("delete Site at SG scope")
  delete is SiteByServiceGroupOps.DeleteSync<Site>;
}

But this external resource could only be defined as a resource group resource. In this case, the service group resource is actually a tenant resource.
How could I do it? Shall we consider adding a Scope argument in this ExternalResource template?

[ArcturusZhang]

BTW, thanks to @pshao25 , we could use BaseParameters optional argument in ResourceInstanceParameters template to remove those extra parameters like subscriptionId in this way:

alias SiteByServiceGroupOps = Azure.ResourceManager.Legacy.ExtensionOperations<
  ResourceInstanceParameters<ServiceGroup, BaseParameters = Foundations.TenantBaseParameters>,
  Extension.ExtensionProviderNamespace<Site>,
  {
    ...Extension.ExtensionProviderNamespace<Site>;
    ...KeysOf<Site>;
  }
>;

but this hits the bug of providers in this issue
See this playground: playground

Same as the other issue, if I remove the Sites interface, the provider namespace will be corrected: playground

[markcowl]

You should not use legacy templates for this, the idea is to do this

But if we aren't omitting unreachable types, it might make sense to have some additional templates, or an optional template parameter, to avoid having the extra model in the typegraph.

[markcowl]

Note that, Microsoft.Management is a special RP that introduces types like 'managementGroup' that we have built-in types for in the extension library, because they are used so often. If ServiceGroup is used similarly (and widely), the best solution would be to have a built-in type for it.

[markcowl]

My guess is that, other than built-in and specialty resources (such as those in Microsoft.Management), extending specific tenant-level resources is pretty rare.

If we can use and decorate models built from externalResource, then this is what we should do. If we need to keep the extra model out of the type graph, then we should have some kind of support here.

It may make sense to have ServiceGroups as a built-in resource, as ManagementGroups is, which may resolve the problem altogether.

[ArcturusZhang]

@markcowl yes serviceGroups should be a built-in resource. It comes from the same RP as management group and per its documentation, this is a replacement for the old management groups.
But the only issue is that this resource serviceGroup, is in a preview api-version.
I am not sure if they would remove it in the future or not - but based on how it is used right now, it should be built-in.

[ArcturusZhang]

Hi @markcowl
Extension templates work fine - I am able to write the typespec in a very elegant way!
Here is the PR: Azure/azure-rest-api-specs#37409
now the only issue is about the unreachable model.
I think we should have a new template allowing us to define ExternalResource with a specified scope, this should be a general need, and we could provide a new built-in resource ServiceGroup, and ServiceGroup could be defined using the new template (as well as the built-in management group resource).

This RP's swagger previously had an unreachable type - I cannot add the config because adding the config would remove that model. I would not like to do that.

[ArcturusZhang]

@markcowl
so I think we are proposing two solutions:

1. define a new built-in resource ServiceGroup in resource manager library.
2. define a new template or modify the existing ExternalResource to let us generally define resources under other scope than resource group as external resource, which should be useful in other RPs.

I personally prefer 2.
This is because I notice the resource ServiceGroup from the managementGroup RP is in a preview api-version. It might be problematic to introduce that into our library.

[pshao25]

I think we need to go with option 2. https://github.com/Azure/azure-rest-api-specs/pull/37162/files#r2371338648 this is another case whose path is

/providers/microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}/providers/microsoft.Consumption/credits/balanceSummary