[Discussion] UCP Resource ID scheme change

youngbupark commented 1 year ago

Problem

The current UCP resource ID always includes the following root scope. This is designed to support multiple cloud control planes. It works well for the current scenarios.

/planes/{plane type}/{plane name}/resourceGroups/{resourceGroup}/...

However, Radius contributors used to get confused about {plane name} until they find the design doc; some don't understand the meaning of {plane name}.

For instance, I used to get the following questions for each plane:

# For radius resource, what is the meaning of `local` ? 
/planes/radius/local/resourcegroups/localrp/providers/applications.core/environments/your-environment

# For UCP Azure resource, what's the meaning of `azurecloud`?
/planes/azure/azurecloud/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/testGroup/providers/Microsoft.KeyVault/vaults/vault0

# For AWS resource, what's the meaning of `aws` ? 
/planes/aws/aws/accounts/1234567/regions/us-east-1/providers/AWS.Kinesis/Stream/stream-1

Proposal & discussion

Except for /planes/{plane type}/{plane name} in the root scope of resource ID, the rest of API path follows the scheme {entity group}/{entity name}. {entity group}/{entity name} format is helpful to understand the meaning of {entity name}. So I propose to add the entity group name for {plane name} to make resource id more self-descriptive. For example, If we add namespaces(or something else) as entity group for {plane name}, then we may have this scope path.

/planes/{plane type}/namespace/{plane name}

# For radius resource
/planes/radius/namespaces/local/resourcegroups/localrp/providers/applications.core/environments/your-environment

# For UCP Azure resource
/planes/azure/namespaces/azurecloud/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/testGroup/providers/Microsoft.KeyVault/vaults/vault0

# For AWS resource
/planes/aws/namespaces/aws/accounts/1234567/regions/us-east-1/providers/AWS.Kinesis/Stream/stream-1

We can have the following benefits by adding namespaces group name to {plane name}:

It self-describes the part of {plane name}
The scope part can have the consistent API design for the rest of resource id scheme.
We can introduce CRUDL API at {plane type} level with consistent ARM API contract in the future.

Notes

{entity group}/{entity name} is popular, recommended way to design a restful API. ARM, Openshift, and Kubernetes APIs are also good examples to use this scheme.
namespaces is a temporarily proposed name. We will find the better name later.

AB#7702

AB#9516

youngbupark commented 1 year ago

@vinayada1 @rynowak @AaronCrawfis @shalabhms @vishwahiremat / WDYT?

ytimocin commented 1 year ago

I can agree that at first, I was also a little bit confused about the local part of /planes/radius/local.

Can a plane have multiple namespaces? If so, what would be some examples of different namespaces in /planes/azure for example?

How would having different namespaces for the same plane affect the way we process resources?

kachawla commented 1 year ago

I understand the problem and agree with the idea, but not too keen on the using namespaces for this. Each user will have their own bias on what it is depending on the ecosystem that they are most familiar with, for example for AWS partition is what makes most sense here.

youngbupark commented 1 year ago

I understand the problem and agree with the idea, but not too keen on the using namespaces for this. Each user will have their own bias on what it is depending on the ecosystem that they are most familiar with, for example for AWS partition is what makes most sense here.

namespaces is an example we can use :) definitely, we need to find the better name if we decide to have this change.

nithyatsu commented 1 year ago

I wonder if 'cloudinstance' or 'cloudenvironment' is a good name.. "local" indicates radius instance is running local to the current cluster (in same cluster), azurecloud again is the cloud instance name ... ref: https://learn.microsoft.com/en-us/azure/azure-government/compare-azure-government-global-azure has the text:

You can use AzureCLI or PowerShell to obtain Azure Government endpoints for services you provisioned:

Use Azure CLI to run the [az cloud show](https://learn.microsoft.com/en-us/cli/azure/cloud#az-cloud-show) command and provide AzureUSGovernment as the name of the target cloud environment. For example,

Azure CLI

Copy
az cloud show --name AzureUSGovernment
should get you different endpoints for Azure Government.

Use a PowerShell cmdlet such as [Get-AzEnvironment](https://learn.microsoft.com/en-us/powershell/module/az.accounts/get-azenvironment) to get endpoints and metadata for an instance of Azure service. For example,

PowerShell

Copy
Get-AzEnvironment -Name AzureUSGovernment
should get you properties for Azure Government. This cmdlet gets environments from your subscription data file.

vinayada1 commented 1 year ago

Could you provide a few more examples for how the following would change to understand this better?

/planes/radius/local/resourcegroups/localrp/providers/applications.core/environments/your-environment
/planes/azure/azurecloud/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/testGroup/providers/Microsoft.KeyVault/vaults/vault0
/planes/aws/aws/accounts/1234567/regions/us-east-1/providers/AWS.Kinesis/Stream/stream-1

rynowak commented 1 year ago

I like the idea of this, even though it would be a very big change. I'm not convinced yet that it's worth the churn, but we should continue the discussion. I think if we had come up with this design from the start it would be a no-brainer.

If we wanted to pick a single term that applies to all planes, I think that term would be instances. Namespace is already too overloaded.

We should consider also adding the constant segment but allowing it to be different per-plane-type. Examples:

/planes/radius/instances/local/resourcegroups/localrp/providers/applications.core/environments/your-environment
/planes/aws/clouds/aws/accounts/1234567/regions/us-east-1/providers/AWS.Kinesis/Stream/stream-1
/planes/kubernetes/clusters/<guid>/namespaces/default/providers/kubernetes.apps/deployments/myapp

There are two reasons I want to call out why plane name exists in the first place:

Because in practice there is always more than one instance of everything. This allows UCP to be multi-tenant with-respect-to AWS, and Azure, and Kubernetes, and even Radius.
To support regional or other hierarchical routing for federation. Having each UCP instance be aware of not only the types of planes, but the instances of planes enables us to build a geo-redundant and federated control-plane without single points of failure.

So I guess if we make a change to the syntax of UCP resource IDs, we should make sure that UCP is still aware of the instances as well as the types.

rynowak commented 1 year ago

We can introduce CRUDL API at {plane type} level with consistent ARM API contract in the future.

I also want to mention that we already have run into this inconsistency and I don't think we solved it adequately. What's the right URL to list all of the plane types? What's the right URL to list of the instances of a given plane type? I think we're missing one of these features today.

radius-project / radius