• 1: SPEKTRA Edge Meta Service API
• 1.1:
• 1.2:
• 2: SPEKTRA Edge IAM Service API
• 2.1:
• 2.2:
• 3: SPEKTRA Edge Audit Service API
• 3.1:
• 3.2:
• 4: SPEKTRA Edge Limits Service API
• 4.1:
• 4.2:
• 5: SPEKTRA Edge Monitoring Service API
• 5.1: RollupConnector Service APIv2
• 5.2:
• 5.3:
• 6: SPEKTRA Edge Logging Service API
• 6.1:
• 6.2:
• 7: SPEKTRA Edge Proxies Service API
• 7.1:
• 7.2:
• 8: SPEKTRA Edge Secrets Service API
• 8.1:
• 8.2:
• 9: SPEKTRA Edge Devices Service API
• 9.1:
• 9.2:
• 10: SPEKTRA Edge Applications Service API
• 10.1:
• 10.2:
• 11:
• 12: Common types
• 12.1:
• 12.2:
• 12.3:
• 13: DiagnosticsMixin Service APIv1
• 14: LimitsMixin Service APIv1
• 15: ShardingMixin Service APIv1
• 16: DiagnosticsMixin Service APIv1alpha2
• 17: LimitsMixin Service APIv1alpha2
• 18: MetaMixin Service APIv1alpha2

1 - SPEKTRA Edge Meta Service API

Meta is a core, reflection service for the whole SPEKTRA Edge ecosystem. It allows all services on the SPEKTRA Edge platform to gain access to the ecosystem which consists of:

• regions.
• services with deployments and resources.

Meta service allows us to see in which regions the ecosystem is deployed, what services each region offers, what are possible services in general and what resources they have declared.

It underpins several features like multi-region routing (thanks to knowledge of regions and deployments), Limits (thanks to knowledge of resources), garbage collection (thanks to the knowledge of all service schemas and their relationship with each other).

Note that some services are public, some private (and viewing them may be rejected).

Full API Specifications (with resources):

• Version v1alpha2
• Version v1

Resources

Deployments

A deployment represents an instance of a chosen service in a particular region (backend service). It contains some basic information, API version number available (currently active), regional public endpoint, location, etc.

Regions

A region represents a single region where services can hold their deployments.

Services

A service represents some particular service on the SPEKTRA Edge platform, for example, devices.edgelq.com. Organization admins can even deploy their services, too.

Each Service must belong to some service project, from which it inherits all role bindings.

1.1 -

Service meta.goten.com in version v1, proto package goten.meta.v1

Here is the list of resources supported in Meta service APIv1:

• Deployment resource
• Region resource
• Resource resource
• Service resource

Deployment Resource

Deployment Resource describes deployment of service in specific regional cluster (may be multi-zonal). It contains accessibility details.

Name patterns:

• services/{service}/deployments/{deployment}

Parent resources:

• Service

This section covers the methods and messages to interact with Deployment resource.

Deployment Methods

Here is the list of Deployment resource methods:

• GetDeployment method
• BatchGetDeployments method
• ListDeployments method
• WatchDeployment method
• WatchDeployments method
• CreateDeployment method
• UpdateDeployment method
• DeleteDeployment method
• BeginUpgrade method
• SetAvailableUpgrade method
• NotifyShardsUpgradeReadiness method
• GetOrRegisterDataUpdateTask method
• UpdateDataTaskUpdate method

GetDeployment Method

GetDeployment

rpc GetDeployment(GetDeploymentRequest) returns (Deployment)

with the following messages:

• GetDeploymentRequest request message
• Deployment response message

Required Permissions:

• services/meta.goten.com/permissions/deployments.get

The equivalent REST API is:

GET /meta/v1/{name=services/*/deployments/*} 

BatchGetDeployments Method

BatchGetDeployments

rpc BatchGetDeployments(BatchGetDeploymentsRequest) returns (BatchGetDeploymentsResponse)

with the following messages:

• BatchGetDeploymentsRequest request message
• BatchGetDeploymentsResponse response message

Required Permissions:

• services/meta.goten.com/permissions/deployments.batchGet

The equivalent REST API is:

GET /meta/v1/deployments:batchGet 

ListDeployments Method

ListDeployments

rpc ListDeployments(ListDeploymentsRequest) returns (ListDeploymentsResponse)

with the following messages:

• ListDeploymentsRequest request message
• ListDeploymentsResponse response message

Required Permissions:

• services/meta.goten.com/permissions/deployments.list

The equivalent REST API is:

GET /meta/v1/{parent=services/*}/deployments 

WatchDeployment Method

WatchDeployment

rpc WatchDeployment(WatchDeploymentRequest) returns (WatchDeploymentResponse)

with the following messages:

• WatchDeploymentRequest request message
• WatchDeploymentResponse response message

Required Permissions:

• services/meta.goten.com/permissions/deployments.watch

The equivalent REST API is:

POST /meta/v1/{name=services/*/deployments/*}:watch 

WatchDeployments Method

WatchDeployments

rpc WatchDeployments(WatchDeploymentsRequest) returns (WatchDeploymentsResponse)

with the following messages:

• WatchDeploymentsRequest request message
• WatchDeploymentsResponse response message

Required Permissions:

• services/meta.goten.com/permissions/deployments.watch

The equivalent REST API is:

POST /meta/v1/{parent=services/*}/deployments:watch 

CreateDeployment Method

CreateDeployment

rpc CreateDeployment(CreateDeploymentRequest) returns (Deployment)

with the following messages:

• CreateDeploymentRequest request message
• Deployment response message

Required Permissions:

• services/meta.goten.com/permissions/deployments.create

The equivalent REST API is:

POST /meta/v1/{parent=services/*}/deployments (BODY: deployment)

UpdateDeployment Method

UpdateDeployment

rpc UpdateDeployment(UpdateDeploymentRequest) returns (Deployment)

with the following messages:

• UpdateDeploymentRequest request message
• Deployment response message

Required Permissions:

• services/meta.goten.com/permissions/deployments.update

The equivalent REST API is:

PUT /meta/v1/{deployment.name=services/*/deployments/*} (BODY: deployment)

DeleteDeployment Method

DeleteDeployment

rpc DeleteDeployment(DeleteDeploymentRequest) returns (Empty)

with the following messages:

• DeleteDeploymentRequest request message
• Empty response message

Required Permissions:

• services/meta.goten.com/permissions/deployments.delete

The equivalent REST API is:

DELETE /meta/v1/{name=services/*/deployments/*} 

BeginUpgrade Method

BeginUpgrade

rpc BeginUpgrade(BeginUpgradeRequest) returns (Empty)

with the following messages:

• BeginUpgradeRequest request message
• Empty response message

Required Permissions:

• services/meta.goten.com/permissions/deployments.beginUpgrade

The equivalent REST API is:

POST /meta/v1/{name=services/*/deployments/*}:beginUpgrade 

SetAvailableUpgrade Method

SetAvailableUpgrade

rpc SetAvailableUpgrade(SetAvailableUpgradeRequest) returns (Empty)

with the following messages:

• SetAvailableUpgradeRequest request message
• Empty response message

Required Permissions:

• services/meta.goten.com/permissions/deployments.setAvailableUpgrade

The equivalent REST API is:

POST /meta/v1/{name=services/*/deployments/*}:setAvailableUpgrade 

NotifyShardsUpgradeReadiness Method

NotifyShardsUpgradeReadiness

rpc NotifyShardsUpgradeReadiness(NotifyShardsUpgradeReadinessRequest) returns (Empty)

with the following messages:

• NotifyShardsUpgradeReadinessRequest request message
• Empty response message

Required Permissions:

• services/meta.goten.com/permissions/deployments.notifyShardsUpgradeReadiness

The equivalent REST API is:

POST /meta/v1/{name=services/*/deployments/*}:notifyShardsUpgradeReadiness 

GetOrRegisterDataUpdateTask Method

GetOrRegisterDataUpdateTask

rpc GetOrRegisterDataUpdateTask(GetOrRegisterDataUpdateTaskRequest) returns (GetOrRegisterDataUpdateTaskResponse)

with the following messages:

• GetOrRegisterDataUpdateTaskRequest request message
• GetOrRegisterDataUpdateTaskResponse response message

Required Permissions:

• services/meta.goten.com/permissions/deployments.getOrRegisterDataUpdateTask

The equivalent REST API is:

POST /meta/v1/{name=services/*/deployments/*}:getOrRegisterDataUpdateTask 

UpdateDataTaskUpdate Method

UpdateDataTaskUpdate

rpc UpdateDataTaskUpdate(UpdateDataTaskUpdateRequest) returns (Empty)

with the following messages:

• UpdateDataTaskUpdateRequest request message
• Empty response message

Required Permissions:

• services/meta.goten.com/permissions/deployments.updateDataTaskUpdate

The equivalent REST API is:

POST /meta/v1/{name=services/*/deployments/*}:updateDataTaskUpdate 

Deployment Messages

Here is the list of Deployment resource messages:

• Deployment message
• Deployment.Location message
• Deployment.UpgradeState message
• Deployment.AvailableUpgrade message
• Deployment.DbUpdateTaskStatus message
• GetDeploymentRequest message
• BatchGetDeploymentsRequest message
• BatchGetDeploymentsResponse message
• ListDeploymentsRequest message
• ListDeploymentsResponse message
• WatchDeploymentRequest message
• WatchDeploymentResponse message
• WatchDeploymentsRequest message
• WatchDeploymentsResponse message
• WatchDeploymentsResponse.PageTokenChange message
• CreateDeploymentRequest message
• CreateDeploymentRequest.ResponseMask message
• UpdateDeploymentRequest message
• UpdateDeploymentRequest.CAS message
• UpdateDeploymentRequest.ResponseMask message
• DeleteDeploymentRequest message
• BeginUpgradeRequest message
• SetAvailableUpgradeRequest message
• NotifyShardsUpgradeReadinessRequest message
• GetOrRegisterDataUpdateTaskRequest message
• GetOrRegisterDataUpdateTaskResponse message
• UpdateDataTaskUpdateRequest message

Deployment Message

Deployment.Location Message

Location describes deployment location of this deployment. It may be used for multi-region routing to help determine closest deployment.

Deployment.UpgradeState Message

UpgradeState describes current state of database major upgrade. This corresponds to database migrations, API upgrades, other internal updates (if needed).

Deployment.AvailableUpgrade Message

Deployment.DbUpdateTaskStatus Message

GetDeploymentRequest Message

A request message of the GetDeployment method.

BatchGetDeploymentsRequest Message

A request message of the BatchGetDeployments method.

BatchGetDeploymentsResponse Message

A response message of the BatchGetDeployments method.

ListDeploymentsRequest Message

A request message of the ListDeployments method.

ListDeploymentsResponse Message

A response message of the ListDeployments method.

WatchDeploymentRequest Message

A request message of the WatchDeployment method.

WatchDeploymentResponse Message

A response message of the WatchDeployment method.

WatchDeploymentsRequest Message

A request message of the WatchDeployments method.

WatchDeploymentsResponse Message

A response message of the WatchDeployments method.

WatchDeploymentsResponse.PageTokenChange Message

CreateDeploymentRequest Message

A request message of the CreateDeployment method.

CreateDeploymentRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

UpdateDeploymentRequest Message

A request message of the UpdateDeployment method.

UpdateDeploymentRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

UpdateDeploymentRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

DeleteDeploymentRequest Message

A request message of the DeleteDeployment method.

BeginUpgradeRequest Message

Request message for method [BeginUpgrade][goten.meta.v1.BeginUpgrade]

SetAvailableUpgradeRequest Message

Request message for method [SetAvailableUpgrade][goten.meta.v1.SetAvailableUpgrade]

NotifyShardsUpgradeReadinessRequest Message

Request message for method [NotifyShardsUpgradeReadiness][goten.meta.v1.NotifyShardsUpgradeReadiness]

GetOrRegisterDataUpdateTaskRequest Message

Request message for method [GetOrRegisterDataUpdateTask][goten.meta.v1.GetOrRegisterDataUpdateTask]

GetOrRegisterDataUpdateTaskResponse Message

Response message for method [GetOrRegisterDataUpdateTask][goten.meta.v1.GetOrRegisterDataUpdateTask]

UpdateDataTaskUpdateRequest Message

Request message for method [UpdateDataTaskUpdate][goten.meta.v1.UpdateDataTaskUpdate]

Deployment Enumerations

Here is the list of Deployment resource enumerations:

• Deployment.UpgradeState.Stage enumeration

Deployment.UpgradeState.Stage Enumeration

Region Resource

Region Resource is an auxiliary resource that provides geographic scope to resources in Goten services, ideally should point to narrow geographic location but Goten is not strict about it. This allows case where in single physical location we have multiple clusters using different virtual networks hosting different deployments. Goten uses regions to aid in global scaling, but otherwise tries to abstract from running hardware focusing on services instead.

Name patterns:

• regions/{region}

This section covers the methods and messages to interact with Region resource.

Region Methods

Here is the list of Region resource methods:

• GetRegion method
• BatchGetRegions method
• ListRegions method
• WatchRegion method
• WatchRegions method
• CreateRegion method
• UpdateRegion method
• DeleteRegion method

GetRegion Method

GetRegion

rpc GetRegion(GetRegionRequest) returns (Region)

with the following messages:

• GetRegionRequest request message
• Region response message

Required Permissions:

• services/meta.goten.com/permissions/regions.get

The equivalent REST API is:

GET /meta/v1/{name=regions/*} 

BatchGetRegions Method

BatchGetRegions

rpc BatchGetRegions(BatchGetRegionsRequest) returns (BatchGetRegionsResponse)

with the following messages:

• BatchGetRegionsRequest request message
• BatchGetRegionsResponse response message

Required Permissions:

• services/meta.goten.com/permissions/regions.batchGet

The equivalent REST API is:

GET /meta/v1/regions:batchGet 

ListRegions Method

ListRegions

rpc ListRegions(ListRegionsRequest) returns (ListRegionsResponse)

with the following messages:

• ListRegionsRequest request message
• ListRegionsResponse response message

Required Permissions:

• services/meta.goten.com/permissions/regions.list

The equivalent REST API is:

GET /meta/v1/regions 

WatchRegion Method

WatchRegion

rpc WatchRegion(WatchRegionRequest) returns (WatchRegionResponse)

with the following messages:

• WatchRegionRequest request message
• WatchRegionResponse response message

Required Permissions:

• services/meta.goten.com/permissions/regions.watch

The equivalent REST API is:

POST /meta/v1/{name=regions/*}:watch 

WatchRegions Method

WatchRegions

rpc WatchRegions(WatchRegionsRequest) returns (WatchRegionsResponse)

with the following messages:

• WatchRegionsRequest request message
• WatchRegionsResponse response message

Required Permissions:

• services/meta.goten.com/permissions/regions.watch

The equivalent REST API is:

POST /meta/v1/regions:watch 

CreateRegion Method

CreateRegion

rpc CreateRegion(CreateRegionRequest) returns (Region)

with the following messages:

• CreateRegionRequest request message
• Region response message

Required Permissions:

• services/meta.goten.com/permissions/regions.create

The equivalent REST API is:

POST /meta/v1/regions (BODY: region)

UpdateRegion Method

UpdateRegion

rpc UpdateRegion(UpdateRegionRequest) returns (Region)

with the following messages:

• UpdateRegionRequest request message
• Region response message

Required Permissions:

• services/meta.goten.com/permissions/regions.update

The equivalent REST API is:

PUT /meta/v1/{region.name=regions/*} (BODY: region)

DeleteRegion Method

DeleteRegion

rpc DeleteRegion(DeleteRegionRequest) returns (Empty)

with the following messages:

• DeleteRegionRequest request message
• Empty response message

Required Permissions:

• services/meta.goten.com/permissions/regions.delete

The equivalent REST API is:

DELETE /meta/v1/{name=regions/*} 

Region Messages

Here is the list of Region resource messages:

• Region message
• GetRegionRequest message
• BatchGetRegionsRequest message
• BatchGetRegionsResponse message
• ListRegionsRequest message
• ListRegionsResponse message
• WatchRegionRequest message
• WatchRegionResponse message
• WatchRegionsRequest message
• WatchRegionsResponse message
• WatchRegionsResponse.PageTokenChange message
• CreateRegionRequest message
• CreateRegionRequest.ResponseMask message
• UpdateRegionRequest message
• UpdateRegionRequest.CAS message
• UpdateRegionRequest.ResponseMask message
• DeleteRegionRequest message

Region Message

GetRegionRequest Message

A request message of the GetRegion method.

BatchGetRegionsRequest Message

A request message of the BatchGetRegions method.

BatchGetRegionsResponse Message

A response message of the BatchGetRegions method.

ListRegionsRequest Message

A request message of the ListRegions method.

ListRegionsResponse Message

A response message of the ListRegions method.

WatchRegionRequest Message

A request message of the WatchRegion method.

WatchRegionResponse Message

A response message of the WatchRegion method.

WatchRegionsRequest Message

A request message of the WatchRegions method.

WatchRegionsResponse Message

A response message of the WatchRegions method.

WatchRegionsResponse.PageTokenChange Message

CreateRegionRequest Message

A request message of the CreateRegion method.

CreateRegionRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

UpdateRegionRequest Message

A request message of the UpdateRegion method.

UpdateRegionRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

UpdateRegionRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

DeleteRegionRequest Message

A request message of the DeleteRegion method.

Resource Resource

Resource Resource

Name patterns:

• services/{service}/resources/{resource}

Parent resources:

• Service

This section covers the methods and messages to interact with Resource resource.

Resource Methods

Here is the list of Resource resource methods:

• GetResource method
• BatchGetResources method
• ListResources method
• WatchResource method
• WatchResources method
• CreateResource method
• UpdateResource method
• DeleteResource method

GetResource Method

GetResource

rpc GetResource(GetResourceRequest) returns (Resource)

with the following messages:

• GetResourceRequest request message
• Resource response message

Required Permissions:

• services/meta.goten.com/permissions/resources.get

The equivalent REST API is:

GET /meta/v1/{name=services/*/resources/*} 

BatchGetResources Method

BatchGetResources

rpc BatchGetResources(BatchGetResourcesRequest) returns (BatchGetResourcesResponse)

with the following messages:

• BatchGetResourcesRequest request message
• BatchGetResourcesResponse response message

Required Permissions:

• services/meta.goten.com/permissions/resources.batchGet

The equivalent REST API is:

GET /meta/v1/resources:batchGet 

ListResources Method

ListResources

rpc ListResources(ListResourcesRequest) returns (ListResourcesResponse)

with the following messages:

• ListResourcesRequest request message
• ListResourcesResponse response message

Required Permissions:

• services/meta.goten.com/permissions/resources.list

The equivalent REST API is:

GET /meta/v1/{parent=services/*}/resources 

WatchResource Method

WatchResource

rpc WatchResource(WatchResourceRequest) returns (WatchResourceResponse)

with the following messages:

• WatchResourceRequest request message
• WatchResourceResponse response message

Required Permissions:

• services/meta.goten.com/permissions/resources.watch

The equivalent REST API is:

POST /meta/v1/{name=services/*/resources/*}:watch 

WatchResources Method

WatchResources

rpc WatchResources(WatchResourcesRequest) returns (WatchResourcesResponse)

with the following messages:

• WatchResourcesRequest request message
• WatchResourcesResponse response message

Required Permissions:

• services/meta.goten.com/permissions/resources.watch

The equivalent REST API is:

POST /meta/v1/{parent=services/*}/resources:watch 

CreateResource Method

CreateResource

rpc CreateResource(CreateResourceRequest) returns (Resource)

with the following messages:

• CreateResourceRequest request message
• Resource response message

Required Permissions:

• services/meta.goten.com/permissions/resources.create

The equivalent REST API is:

POST /meta/v1/{parent=services/*}/resources (BODY: resource)

UpdateResource Method

UpdateResource

rpc UpdateResource(UpdateResourceRequest) returns (Resource)

with the following messages:

• UpdateResourceRequest request message
• Resource response message

Required Permissions:

• services/meta.goten.com/permissions/resources.update

The equivalent REST API is:

PUT /meta/v1/{resource.name=services/*/resources/*} (BODY: resource)

DeleteResource Method

DeleteResource

rpc DeleteResource(DeleteResourceRequest) returns (Empty)

with the following messages:

• DeleteResourceRequest request message
• Empty response message

Required Permissions:

• services/meta.goten.com/permissions/resources.delete

The equivalent REST API is:

DELETE /meta/v1/{name=services/*/resources/*} 

Resource Messages

Here is the list of Resource resource messages:

• Resource message
• Resource.VersionedInfo message
• GetResourceRequest message
• BatchGetResourcesRequest message
• BatchGetResourcesResponse message
• ListResourcesRequest message
• ListResourcesResponse message
• WatchResourceRequest message
• WatchResourceResponse message
• WatchResourcesRequest message
• WatchResourcesResponse message
• WatchResourcesResponse.PageTokenChange message
• CreateResourceRequest message
• CreateResourceRequest.ResponseMask message
• UpdateResourceRequest message
• UpdateResourceRequest.CAS message
• UpdateResourceRequest.ResponseMask message
• DeleteResourceRequest message

Resource Message

Resource.VersionedInfo Message

VersionedInfo contains specification part that is versioned.

GetResourceRequest Message

A request message of the GetResource method.

BatchGetResourcesRequest Message

A request message of the BatchGetResources method.

BatchGetResourcesResponse Message

A response message of the BatchGetResources method.

ListResourcesRequest Message

A request message of the ListResources method.

ListResourcesResponse Message

A response message of the ListResources method.

WatchResourceRequest Message

A request message of the WatchResource method.

WatchResourceResponse Message

A response message of the WatchResource method.

WatchResourcesRequest Message

A request message of the WatchResources method.

WatchResourcesResponse Message

A response message of the WatchResources method.

WatchResourcesResponse.PageTokenChange Message

CreateResourceRequest Message

A request message of the CreateResource method.

CreateResourceRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

UpdateResourceRequest Message

A request message of the UpdateResource method.

UpdateResourceRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

UpdateResourceRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

DeleteResourceRequest Message

A request message of the DeleteResource method.

Service Resource

Service Resource contains service description like domain under which it can be accessed, versions, imported services and their versions.

Name patterns:

• services/{service}

This section covers the methods and messages to interact with Service resource.

Service Methods

Here is the list of Service resource methods:

• GetService method
• BatchGetServices method
• ListServices method
• WatchService method
• WatchServices method
• CreateService method
• UpdateService method
• DeleteService method

GetService Method

GetService

rpc GetService(GetServiceRequest) returns (Service)

with the following messages:

• GetServiceRequest request message
• Service response message

Required Permissions:

• services/meta.goten.com/permissions/services.get

The equivalent REST API is:

GET /meta/v1/{name=services/*} 

BatchGetServices Method

BatchGetServices

rpc BatchGetServices(BatchGetServicesRequest) returns (BatchGetServicesResponse)

with the following messages:

• BatchGetServicesRequest request message
• BatchGetServicesResponse response message

Required Permissions:

• services/meta.goten.com/permissions/services.batchGet

The equivalent REST API is:

GET /meta/v1/services:batchGet 

ListServices Method

ListServices

rpc ListServices(ListServicesRequest) returns (ListServicesResponse)

with the following messages:

• ListServicesRequest request message
• ListServicesResponse response message

Required Permissions:

• services/meta.goten.com/permissions/services.list

The equivalent REST API is:

GET /meta/v1/services 

WatchService Method

WatchService

rpc WatchService(WatchServiceRequest) returns (WatchServiceResponse)

with the following messages:

• WatchServiceRequest request message
• WatchServiceResponse response message

Required Permissions:

• services/meta.goten.com/permissions/services.watch

The equivalent REST API is:

POST /meta/v1/{name=services/*}:watch 

WatchServices Method

WatchServices

rpc WatchServices(WatchServicesRequest) returns (WatchServicesResponse)

with the following messages:

• WatchServicesRequest request message
• WatchServicesResponse response message

Required Permissions:

• services/meta.goten.com/permissions/services.watch

The equivalent REST API is:

POST /meta/v1/services:watch 

CreateService Method

CreateService

rpc CreateService(CreateServiceRequest) returns (Service)

with the following messages:

• CreateServiceRequest request message
• Service response message

Required Permissions:

• services/meta.goten.com/permissions/services.create

The equivalent REST API is:

POST /meta/v1/services (BODY: service)

UpdateService Method

UpdateService

rpc UpdateService(UpdateServiceRequest) returns (Service)

with the following messages:

• UpdateServiceRequest request message
• Service response message

Required Permissions:

• services/meta.goten.com/permissions/services.update

The equivalent REST API is:

PUT /meta/v1/{service.name=services/*} (BODY: service)

DeleteService Method

DeleteService

rpc DeleteService(DeleteServiceRequest) returns (Empty)

with the following messages:

• DeleteServiceRequest request message
• Empty response message

Required Permissions:

• services/meta.goten.com/permissions/services.delete

The equivalent REST API is:

DELETE /meta/v1/{name=services/*} 

Service Messages

Here is the list of Service resource messages:

• Service message
• Service.ImportedVersions message
• GetServiceRequest message
• BatchGetServicesRequest message
• BatchGetServicesResponse message
• ListServicesRequest message
• ListServicesResponse message
• WatchServiceRequest message
• WatchServiceResponse message
• WatchServicesRequest message
• WatchServicesResponse message
• WatchServicesResponse.PageTokenChange message
• CreateServiceRequest message
• CreateServiceRequest.ResponseMask message
• UpdateServiceRequest message
• UpdateServiceRequest.CAS message
• UpdateServiceRequest.ResponseMask message
• DeleteServiceRequest message

Service Message

Service.ImportedVersions Message

ImportedVersions contains information which version of the imported service is used by current service in specific version.

GetServiceRequest Message

A request message of the GetService method.

BatchGetServicesRequest Message

A request message of the BatchGetServices method.

BatchGetServicesResponse Message

A response message of the BatchGetServices method.

ListServicesRequest Message

A request message of the ListServices method.

ListServicesResponse Message

A response message of the ListServices method.

WatchServiceRequest Message

A request message of the WatchService method.

WatchServiceResponse Message

A response message of the WatchService method.

WatchServicesRequest Message

A request message of the WatchServices method.

WatchServicesResponse Message

A response message of the WatchServices method.

WatchServicesResponse.PageTokenChange Message

CreateServiceRequest Message

A request message of the CreateService method.

CreateServiceRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

UpdateServiceRequest Message

A request message of the UpdateService method.

UpdateServiceRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

UpdateServiceRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

DeleteServiceRequest Message

A request message of the DeleteService method.

Meta Service Shared Methods and Messages

Meta Service Shared Messages

Here is the list of Meta service shared messages:

• DeploymentChange message
• DeploymentChange.Added message
• DeploymentChange.Current message
• DeploymentChange.Modified message
• DeploymentChange.Removed message
• LabelledDomain message
• RegionChange message
• RegionChange.Added message
• RegionChange.Current message
• RegionChange.Modified message
• RegionChange.Removed message
• ResourceChange message
• ResourceChange.Added message
• ResourceChange.Current message
• ResourceChange.Modified message
• ResourceChange.Removed message
• ServiceChange message
• ServiceChange.Added message
• ServiceChange.Current message
• ServiceChange.Modified message
• ServiceChange.Removed message

DeploymentChange Message

DeploymentChange is used by Watch notifications Responses to describe change of single Deployment One of Added, Modified, Removed

DeploymentChange.Added Message

Deployment has been added to query view

DeploymentChange.Current Message

Deployment has been added or modified in a query view. Version used for stateless watching

DeploymentChange.Modified Message

Deployment changed some of it’s fields - contains either full document or masked change

DeploymentChange.Removed Message

Removed is returned when Deployment is deleted or leaves Query view

LabelledDomain Message

LabelledDomain provides connectivity information in a context of Service and specific label. Service/Deployment may provide multiple addresses, for example offering different quality class, like optimized for high/low throughput.

RegionChange Message

RegionChange is used by Watch notifications Responses to describe change of single Region One of Added, Modified, Removed

RegionChange.Added Message

Region has been added to query view

RegionChange.Current Message

Region has been added or modified in a query view. Version used for stateless watching

RegionChange.Modified Message

Region changed some of it’s fields - contains either full document or masked change

RegionChange.Removed Message

Removed is returned when Region is deleted or leaves Query view

ResourceChange Message

ResourceChange is used by Watch notifications Responses to describe change of single Resource One of Added, Modified, Removed

ResourceChange.Added Message

Resource has been added to query view

ResourceChange.Current Message

Resource has been added or modified in a query view. Version used for stateless watching

ResourceChange.Modified Message

Resource changed some of it’s fields - contains either full document or masked change

ResourceChange.Removed Message

Removed is returned when Resource is deleted or leaves Query view

ServiceChange Message

ServiceChange is used by Watch notifications Responses to describe change of single Service One of Added, Modified, Removed

ServiceChange.Added Message

Service has been added to query view

ServiceChange.Current Message

Service has been added or modified in a query view. Version used for stateless watching

ServiceChange.Modified Message

Service changed some of it’s fields - contains either full document or masked change

ServiceChange.Removed Message

Removed is returned when Service is deleted or leaves Query view

1.2 -

Service meta.edgelq.com in version v1alpha2, proto package ntt.meta.v1alpha2

Here is the list of resources supported in Meta service APIv1alpha2:

• Deployment resource
• Region resource
• Resource resource
• Service resource

Deployment Resource

Deployment Resource - describes meta information about deployment of a parent Service.

Name patterns:

• regions/{region}/deployments/{deployment}

Parent resources:

• Region

This section covers the methods and messages to interact with Deployment resource.

Deployment Methods

Here is the list of Deployment resource methods:

• GetDeployment method
• BatchGetDeployments method
• ListDeployments method
• WatchDeployment method
• WatchDeployments method

GetDeployment Method

GetDeployment

rpc GetDeployment(GetDeploymentRequest) returns (Deployment)

with the following messages:

• GetDeploymentRequest request message
• Deployment response message

Required Permissions:

• services/meta.edgelq.com/permissions/deployments.get

The equivalent REST API is:

GET /v1alpha2/{name=regions/*/deployments/*} 

BatchGetDeployments Method

BatchGetDeployments

rpc BatchGetDeployments(BatchGetDeploymentsRequest) returns (BatchGetDeploymentsResponse)

with the following messages:

• BatchGetDeploymentsRequest request message
• BatchGetDeploymentsResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/deployments.batchGet

The equivalent REST API is:

GET /v1alpha2/deployments:batchGet 

ListDeployments Method

ListDeployments

rpc ListDeployments(ListDeploymentsRequest) returns (ListDeploymentsResponse)

with the following messages:

• ListDeploymentsRequest request message
• ListDeploymentsResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/deployments.list

The equivalent REST API is:

GET /v1alpha2/{parent=regions/*}/deployments 

WatchDeployment Method

WatchDeployment

rpc WatchDeployment(WatchDeploymentRequest) returns (WatchDeploymentResponse)

with the following messages:

• WatchDeploymentRequest request message
• WatchDeploymentResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/deployments.watch

The equivalent REST API is:

POST /v1alpha2/{name=regions/*/deployments/*}:watch 

WatchDeployments Method

WatchDeployments

rpc WatchDeployments(WatchDeploymentsRequest) returns (WatchDeploymentsResponse)

with the following messages:

• WatchDeploymentsRequest request message
• WatchDeploymentsResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/deployments.watch

The equivalent REST API is:

POST /v1alpha2/{parent=regions/*}/deployments:watch 

Deployment Messages

Here is the list of Deployment resource messages:

• Deployment message
• GetDeploymentRequest message
• BatchGetDeploymentsRequest message
• BatchGetDeploymentsResponse message
• ListDeploymentsRequest message
• ListDeploymentsResponse message
• WatchDeploymentRequest message
• WatchDeploymentResponse message
• WatchDeploymentsRequest message
• WatchDeploymentsResponse message
• WatchDeploymentsResponse.PageTokenChange message

Deployment Message

GetDeploymentRequest Message

A request message of the GetDeployment method.

BatchGetDeploymentsRequest Message

A request message of the BatchGetDeployments method.

BatchGetDeploymentsResponse Message

A response message of the BatchGetDeployments method.

ListDeploymentsRequest Message

A request message of the ListDeployments method.

ListDeploymentsResponse Message

A response message of the ListDeployments method.

WatchDeploymentRequest Message

A request message of the WatchDeployment method.

WatchDeploymentResponse Message

A response message of the WatchDeployment method.

WatchDeploymentsRequest Message

A request message of the WatchDeployments method.

WatchDeploymentsResponse Message

A response message of the WatchDeployments method.

WatchDeploymentsResponse.PageTokenChange Message

Region Resource

Region Resource

Name patterns:

• regions/{region}

This section covers the methods and messages to interact with Region resource.

Region Methods

Here is the list of Region resource methods:

• GetRegion method
• BatchGetRegions method
• ListRegions method
• WatchRegion method
• WatchRegions method

GetRegion Method

GetRegion

rpc GetRegion(GetRegionRequest) returns (Region)

with the following messages:

• GetRegionRequest request message
• Region response message

Required Permissions:

• services/meta.edgelq.com/permissions/regions.get

The equivalent REST API is:

GET /v1alpha2/{name=regions/*} 

BatchGetRegions Method

BatchGetRegions

rpc BatchGetRegions(BatchGetRegionsRequest) returns (BatchGetRegionsResponse)

with the following messages:

• BatchGetRegionsRequest request message
• BatchGetRegionsResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/regions.batchGet

The equivalent REST API is:

GET /v1alpha2/regions:batchGet 

ListRegions Method

ListRegions

rpc ListRegions(ListRegionsRequest) returns (ListRegionsResponse)

with the following messages:

• ListRegionsRequest request message
• ListRegionsResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/regions.list

The equivalent REST API is:

GET /v1alpha2/regions 

WatchRegion Method

WatchRegion

rpc WatchRegion(WatchRegionRequest) returns (WatchRegionResponse)

with the following messages:

• WatchRegionRequest request message
• WatchRegionResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/regions.watch

The equivalent REST API is:

POST /v1alpha2/{name=regions/*}:watch 

WatchRegions Method

WatchRegions

rpc WatchRegions(WatchRegionsRequest) returns (WatchRegionsResponse)

with the following messages:

• WatchRegionsRequest request message
• WatchRegionsResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/regions.watch

The equivalent REST API is:

POST /v1alpha2/regions:watch 

Region Messages

Here is the list of Region resource messages:

• Region message
• Region.RegionLocation message
• Region.RegionConnectivityPreference message
• GetRegionRequest message
• BatchGetRegionsRequest message
• BatchGetRegionsResponse message
• ListRegionsRequest message
• ListRegionsResponse message
• WatchRegionRequest message
• WatchRegionResponse message
• WatchRegionsRequest message
• WatchRegionsResponse message
• WatchRegionsResponse.PageTokenChange message

Region Message

Region.RegionLocation Message

RegionLocation describes deployment location of a region.

Region.RegionConnectivityPreference Message

RegionConnectivityPreference is a hardcoded connectivity score to other region.

GetRegionRequest Message

A request message of the GetRegion method.

BatchGetRegionsRequest Message

A request message of the BatchGetRegions method.

BatchGetRegionsResponse Message

A response message of the BatchGetRegions method.

ListRegionsRequest Message

A request message of the ListRegions method.

ListRegionsResponse Message

A response message of the ListRegions method.

WatchRegionRequest Message

A request message of the WatchRegion method.

WatchRegionResponse Message

A response message of the WatchRegion method.

WatchRegionsRequest Message

A request message of the WatchRegions method.

WatchRegionsResponse Message

A response message of the WatchRegions method.

WatchRegionsResponse.PageTokenChange Message

Resource Resource

Resource Resource

Name patterns:

• services/{service}/resources/{resource}

Parent resources:

• Service

This section covers the methods and messages to interact with Resource resource.

Resource Methods

Here is the list of Resource resource methods:

• GetResource method
• BatchGetResources method
• ListResources method
• WatchResource method
• WatchResources method

GetResource Method

GetResource

rpc GetResource(GetResourceRequest) returns (Resource)

with the following messages:

• GetResourceRequest request message
• Resource response message

Required Permissions:

• services/meta.edgelq.com/permissions/resources.get

The equivalent REST API is:

GET /v1alpha2/{name=services/*/resources/*} 

BatchGetResources Method

BatchGetResources

rpc BatchGetResources(BatchGetResourcesRequest) returns (BatchGetResourcesResponse)

with the following messages:

• BatchGetResourcesRequest request message
• BatchGetResourcesResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/resources.batchGet

The equivalent REST API is:

GET /v1alpha2/resources:batchGet 

ListResources Method

ListResources

rpc ListResources(ListResourcesRequest) returns (ListResourcesResponse)

with the following messages:

• ListResourcesRequest request message
• ListResourcesResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/resources.list

The equivalent REST API is:

GET /v1alpha2/{parent=services/*}/resources 

WatchResource Method

WatchResource

rpc WatchResource(WatchResourceRequest) returns (WatchResourceResponse)

with the following messages:

• WatchResourceRequest request message
• WatchResourceResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/resources.watch

The equivalent REST API is:

POST /v1alpha2/{name=services/*/resources/*}:watch 

WatchResources Method

WatchResources

rpc WatchResources(WatchResourcesRequest) returns (WatchResourcesResponse)

with the following messages:

• WatchResourcesRequest request message
• WatchResourcesResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/resources.watch

The equivalent REST API is:

POST /v1alpha2/{parent=services/*}/resources:watch 

Resource Messages

Here is the list of Resource resource messages:

• Resource message
• GetResourceRequest message
• BatchGetResourcesRequest message
• BatchGetResourcesResponse message
• ListResourcesRequest message
• ListResourcesResponse message
• WatchResourceRequest message
• WatchResourceResponse message
• WatchResourcesRequest message
• WatchResourcesResponse message
• WatchResourcesResponse.PageTokenChange message

Resource Message

GetResourceRequest Message

A request message of the GetResource method.

BatchGetResourcesRequest Message

A request message of the BatchGetResources method.

BatchGetResourcesResponse Message

A response message of the BatchGetResources method.

ListResourcesRequest Message

A request message of the ListResources method.

ListResourcesResponse Message

A response message of the ListResources method.

WatchResourceRequest Message

A request message of the WatchResource method.

WatchResourceResponse Message

A response message of the WatchResource method.

WatchResourcesRequest Message

A request message of the WatchResources method.

WatchResourcesResponse Message

A response message of the WatchResources method.

WatchResourcesResponse.PageTokenChange Message

Service Resource

Service Resource

Name patterns:

• services/{service}

This section covers the methods and messages to interact with Service resource.

Service Methods

Here is the list of Service resource methods:

• GetService method
• BatchGetServices method
• ListServices method
• WatchService method
• WatchServices method

GetService Method

GetService

rpc GetService(GetServiceRequest) returns (Service)

with the following messages:

• GetServiceRequest request message
• Service response message

Required Permissions:

• services/meta.edgelq.com/permissions/services.get

The equivalent REST API is:

GET /v1alpha2/{name=services/*} 

BatchGetServices Method

BatchGetServices

rpc BatchGetServices(BatchGetServicesRequest) returns (BatchGetServicesResponse)

with the following messages:

• BatchGetServicesRequest request message
• BatchGetServicesResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/services.batchGet

The equivalent REST API is:

GET /v1alpha2/services:batchGet 

ListServices Method

ListServices

rpc ListServices(ListServicesRequest) returns (ListServicesResponse)

with the following messages:

• ListServicesRequest request message
• ListServicesResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/services.list

The equivalent REST API is:

GET /v1alpha2/services 

WatchService Method

WatchService

rpc WatchService(WatchServiceRequest) returns (WatchServiceResponse)

with the following messages:

• WatchServiceRequest request message
• WatchServiceResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/services.watch

The equivalent REST API is:

POST /v1alpha2/{name=services/*}:watch 

WatchServices Method

WatchServices

rpc WatchServices(WatchServicesRequest) returns (WatchServicesResponse)

with the following messages:

• WatchServicesRequest request message
• WatchServicesResponse response message

Required Permissions:

• services/meta.edgelq.com/permissions/services.watch

The equivalent REST API is:

POST /v1alpha2/services:watch 

Service Messages

Here is the list of Service resource messages:

• Service message
• GetServiceRequest message
• BatchGetServicesRequest message
• BatchGetServicesResponse message
• ListServicesRequest message
• ListServicesResponse message
• WatchServiceRequest message
• WatchServiceResponse message
• WatchServicesRequest message
• WatchServicesResponse message
• WatchServicesResponse.PageTokenChange message

Service Message

GetServiceRequest Message

A request message of the GetService method.

BatchGetServicesRequest Message

A request message of the BatchGetServices method.

BatchGetServicesResponse Message

A response message of the BatchGetServices method.

ListServicesRequest Message

A request message of the ListServices method.

ListServicesResponse Message

A response message of the ListServices method.

WatchServiceRequest Message

A request message of the WatchService method.

WatchServiceResponse Message

A response message of the WatchService method.

WatchServicesRequest Message

A request message of the WatchServices method.

WatchServicesResponse Message

A response message of the WatchServices method.

WatchServicesResponse.PageTokenChange Message

Meta Service Shared Methods and Messages

Meta Service Shared Messages

Here is the list of Meta service shared messages:

• DeploymentChange message
• DeploymentChange.Added message
• DeploymentChange.Current message
• DeploymentChange.Modified message
• DeploymentChange.Removed message
• RegionChange message
• RegionChange.Added message
• RegionChange.Current message
• RegionChange.Modified message
• RegionChange.Removed message
• ResourceChange message
• ResourceChange.Added message
• ResourceChange.Current message
• ResourceChange.Modified message
• ResourceChange.Removed message
• ServiceChange message
• ServiceChange.Added message
• ServiceChange.Current message
• ServiceChange.Modified message
• ServiceChange.Removed message

DeploymentChange Message

DeploymentChange is used by Watch notifications Responses to describe change of single Deployment One of Added, Modified, Removed

DeploymentChange.Added Message

Deployment has been added to query view

DeploymentChange.Current Message

Deployment has been added or modified in a query view. Version used for stateless watching

DeploymentChange.Modified Message

Deployment changed some of it’s fields - contains either full document or masked change

DeploymentChange.Removed Message

Removed is returned when Deployment is deleted or leaves Query view

RegionChange Message

RegionChange is used by Watch notifications Responses to describe change of single Region One of Added, Modified, Removed

RegionChange.Added Message

Region has been added to query view

RegionChange.Current Message

Region has been added or modified in a query view. Version used for stateless watching

RegionChange.Modified Message

Region changed some of it’s fields - contains either full document or masked change

RegionChange.Removed Message

Removed is returned when Region is deleted or leaves Query view

ResourceChange Message

ResourceChange is used by Watch notifications Responses to describe change of single Resource One of Added, Modified, Removed

ResourceChange.Added Message

Resource has been added to query view

ResourceChange.Current Message

Resource has been added or modified in a query view. Version used for stateless watching

ResourceChange.Modified Message

Resource changed some of it’s fields - contains either full document or masked change

ResourceChange.Removed Message

Removed is returned when Resource is deleted or leaves Query view

ServiceChange Message

ServiceChange is used by Watch notifications Responses to describe change of single Service One of Added, Modified, Removed

ServiceChange.Added Message

Service has been added to query view

ServiceChange.Current Message

Service has been added or modified in a query view. Version used for stateless watching

ServiceChange.Modified Message

Service changed some of it’s fields - contains either full document or masked change

ServiceChange.Removed Message

Removed is returned when Service is deleted or leaves Query view

2 - SPEKTRA Edge IAM Service API

The Identity and Access Management (IAM) service provides an authentication and authorization endpoint for both end-user clients such as the cuttle command and other services that require permission checks.

In IAM, organization or project administrators can manage members assigned permissions via role bindings across managed projects, as below:

During the authentication process, backend services extract the Actor (Who) from JWT tokens. During Authorization, backend services are checking in which scopes (Where) actions are happening, what permissions/roles are required (What), and whether an authenticated Actor has necessary RoleBindings (which binds an Actor with Scope with Role).

Apart from that, Organization admins can create so-called Service Projects, in which they can create their Services. Services on their own are additional IAM Scopes, where administrators also can manage RoleBindings.

Full API Specifications (with resources):

• Version v1alpha2
• Version v1

Resources

Groups

A group is a set of other members. It facilitates authorization management, admins can assign roles to groups instead of individual principals, groups, nor domains.

Members

A member is a similar concept of principal, but it can also represent a groups of users, e.g. group, domain, or wildcard principals, e.g. any one of them. You can think of it as:

Every principals is a member, but not every member is a principal.

Known member types are:

• users:$EMAIL

  A Member of User type (also an principal), where $EMAIL is equal to User Email.

• serviceAccounts:$EMAIL

  A member of service account type (also an principal), where $EMAIL is equal to ServiceAccount E-mail.

• allUsers

  all principals.

• allAuthenticatedUsers

  all authenticated principals.

• domain:$DOMAIN

  Describes all users whose email matches the domain

• group:$EMAIL

  A member of group type, where $EMAIL is equal to group E-mail.

When project/organization/service administrators manage a role binding, they are binding roles with members, not principals. This allows assigning permissions to individual principal, as well as groups of them (bulk).

Organizations

An organization is a hierarchical grouping of sub-organizations and projects that enables the easier resource management and the visibility across entire hierarchies. Granting or revoking permissions through the creation or deletion of role bindings allows access control to be inherited to all sub-organizations and projects.

Permissions

A permission is an atomic and unique resource that identifies the unit of permittable action.

For example, services/devices.edgelq.com/permissions/devices.get corresponds to GetDevice method of devices.edgelq.com service.

Current SPEKTRA Edge supports three types of Permissions:

1. verb permissions

   It’s usually an one-to-one mapped to gRPC method, e.g., services/devices.edgelq.com/permissions/devices.get.

   Method either succeeds or fails depending on the presence of required permission.

2. attach permissions

   With IAM, relationships between resources are protected both ways.

   Role bindings allow the system to control which resources the user is allowed to refer to (or “attach”). For example, the user may have permission to update Device record, but if they try to update spec.serviceAccount, which points to ServiceAccount resource, then the user needs special attach permission on the ServiceAccount itself.

3. field-level Set/Read permissions

   Annotating resource with ntt.annotations.iam.auth_checks.read_checks or ntt.annotations.iam.auth_checks.set_checks will protect single field. Unless the user has this permission, it will:

   • censor (unset) it to get/list responses; or
   • ignore it in update/create requests.

Principals

A principal represents any single entity interacting with the SPEKTRA Edge system.

IAM service and middleware allow all SPEKTRA Edge services to verify Authentication data attached to incoming requests and ensure security by enforcing Access Controls.

IAM recognizes three types of actors: Users, Service Accounts, and Anonymous.

1. A user is actual human who interact with our endpoints (most often through Web dashboards or command-line tools).
2. A service account is usually assigned to a program, like agents, controllers, API servers.
3. An anonymous principal is any unauthenticated request (not JWT token), on rare occasions, it is still valid to allow such traffic. Disabled by default.

Users identify themselves through authentication providers using their IDs, emails, passwords, or SSOs, while service accounts use cryptographic asymmetric key pairs (RSA).

In many cases, users are subject to the multi-factor authentication.

Each user and service account is represented by IAM resource: User/ServiceAccount.

Projects

A project is a logical container for most of the resources present in the system. All devices, applications, and telemetry have a project attached to them.

The project may define the parent organization and inherit all access control from it.

Unlike sub-organizations switching parent organizations, resources within a given project, like devices or pods, cannot easily move to different projects, so make sure you have large-scale [deployments][] well-planned.

Roles

A role is a set of grants with permissions and optional conditions. Typically, administrators should not assign to members individual permissions, as it would require too much work. Instead, we have Roles that contains set of grants, each has an optional sub-scope, conditions, and list of permissions.

Role Bindings

A role binding follows the general principles of RBAC: Role-Based Access Control.

A role can be granted to a member on a scope by creating a corresponding role binding resource.

This results in all matching principals defined in the member field to be able to perform actions defined in roles on the resource in a given scope and its descendant scopes.

Scopes

A scope provides system wide resource groupings. There are four levels of scopes:

1. system-wide

   when resource name pattern doesn’t start with either projects/ or organizations/ or services/.

   Normally users don’t interact very often with system-level resources.

2. organization-scoped

   when the resource name pattern starts with organizations/.

   The organization is a resource in IAM, and it can refer to the parent organization, meaning organizations can form “trees”. Role Bindings are inherited in child organizations. Example: NTT, NTT America, NTT America: Network Innovations

3. project-scoped

   when the resource name pattern starts with projects/ - projects may point to the parent organization.

   Role Bindings from the parent Organization are inherited too.

4. service-scoped

   when the resource name pattern starts with services/ - each service should point to a service project.

   Role Bindings from Service projects are inherited too. If the Service Project has a parent organization, then all Role Bindings are inherited from the whole ancestry path.

Service Projects

A service project is a type of project, in which administrators can create [services][]. A service project is responsible for managing the service accounts that are the service administrators of the project, or for storing usage metrics for the project.

Sub-organizations

A sub-organization is an organization under the parent organization which might contain other organizations. All access permissions granted to higher-level organizations are implicitly inherited to the lower-level organizations and/or projects.

This allows the modeling divisions within a company or the logical groupings for managed customers. Organization administrators can move sub-organization to another organization without delay, so long as they have required permissions on both organizations.

There is no hard limit on the depth of hierarchy, but we recommend keeping it ten or less.

Tenant management

Almost all resources on SPEKTRA Edge are managed based on Project. For example, resources such as Devices and Pods are managed by being tied to a Project. A grouping of resources commonly referred to as a “tenant” is called a Project in SPEKTRA Edge.

Organization is a resource for organizing multiple projects, and a project can be a child of Organization if necessary (projects that do not belong to Organization can also exist). Since an Organization itself can also be a child of an Organization, an Organization and a Project form a tree structure.

Projects are managed by the system or a higher level Organization administrator. Users who are only authorized to operate on specific project cannot perform operations such as creating the project itself.

Creating a project

To create a new Project in an Organization, a user must be assigned the role containing permission services/iam.edgelq.com/permissions/projects.create. Well-known roles that satisfy this condition are:

• services/iam.edgelq.com/roles/scope-admin because it is special Owner role (wildcard)
• services/iam.edgelq.com/roles/admin-operator administrator of SPEKTRA Edge project or organization (core services only).

To create a new project, use the cuttle iam create project command:

cuttle iam create project \
  --title "<project name for humans>" \
  --organization $ORGANIZATION \
  --multi-region-policy '{"enabledRegions": ["eu1"], "defaultControlRegion": "eu1"}' \
  --enabled-services 'services/watchdog.edgelq.com' \
  $PROJECT.

Role Bindings management

The RoleBinding is a resource used to assign privileges to specific users, service accounts, or groups within a Project or Organization. Role Binding itself is also a resource within a Project or Organization, and only users with specific privileges (such as the services/iam.edgelq.com/roles/scope-admin role) can manipulate Role Binding resources.

The privileges granted by Role Binding are dictated by the Role resource. For example, scope-admin is defined as the Role of an owner in an IAM scope (project, organization, service). This role serves as a wildcard (all permissions are granted within scope). Otherwise, in practice, a Role is a collection of multiple Permissions, such as services/iam.edgelq.com/permissions/roleBinding.create, that allows to create RoleBinding (but within scope predicted by RoleBinding).

Permission is a resource that represents the permissions needed to perform the actual operation. As in the previous example, services/iam.edgelq.com/permissions/projects.create is the Permission required to create a Project resource. Note that a Permission may be shared by multiple Roles.

When a user performs an operation, they must possess the necessary Permission to ultimately perform that operation. In practice, a user obtains Permission through a Role by being given a Role Binding in a particular Project.

Note that single user may have multiple roles assigned. In this case, the final Permission granted to the user will be the sum of the Permissions derived from all assigned Roles.

Frequently used roles

Default service roles can be listed by using the cuttle iam list roles --service <service> command. It is advisable to add category filter. For example, to see list of Core SPEKTRA Edge roles for users, we can execute the following:

cuttle iam list roles --service iam.edgelq.com --filter \
  'category IN ["USER","OWNER"]'

In SPEKTRA Edge core services (IAM, devices, applications, monitoring, logging,…), we put all user-relevant roles in service iam.edgelq.com. Third party services, including watchdog, have own list.

Currently, user-facing roles in SPEKTRA Edge core services are:

Creating Role Binding

Role assignments can be performed for users, user groups, and service accounts using the Role Binding resource on IAM.

The following example command assigns devices-operator to a user with an email address of example@edgelq.com. Note that the --member option is in addition to the email address, and that user: is present as a prefix.

cuttle iam create role-binding \
  --role services/iam.edgelq.com/roles/devices-operator \
  --member "user:example@edgelq.com"

Note that the --member option prefix must be serviceAccount: for assigning Role Binding to a service account or group: for a group.

When a Role Binding is created for a group, another one is automatically created for each member in the group. Therefore, multiple Role Bindings may be created even if only one is created from the user’s perspective.

Checking Role Bindings

A list of Role Bindings can be obtained with the following commands:

cuttle iam list role-bindings --organization $ORGANIZATION # for organization
cuttle iam list role-bindings --project $PROJECT # for project
cuttle iam list role-bindings --service $SERVICE # for service (available for service developers)

Checking your access

Check for projects to which you are authorized to access

The command that lists the Project resources present on the system (cuttle iam list projects) cannot be executed by ordinary users for security reasons. If you want to see the projects to which you are entitled, use cuttle iam list-my projects (this command requires -o json, use -o json in combination with jq).

cuttle iam list-my projects -o json | jq .

Check for organizations to which you are authorized to access

The command that lists the Organizations resources present on the system (cuttle iam list organizations) cannot be executed by ordinary users for security reasons, just like for projects. If you want to see the organizations to which you are entitled, use cuttle iam list-my organizations (this command requires -o json, use -o json in combination with jq).

cuttle iam list-my organizations -o json | jq .

Check the roles assigned to you

To check the roles you hold within a particular project, use the cuttle iam check-my role-bindings --project $PROJECT command (this command requires -o json, use jq in combination).

Some example for organization:

cuttle iam check-my role-bindings --parent 'organizations/testing' -o json | jq .
{
  "resolvableGrants": [
    {
      "roleBinding": {
        "name": "roleBindings/edgelq-public-all",
        "role": "services/iam.edgelq.com/roles/edgelq-public"
      },
      "grants": [
        {
          "permissions": [
            "services/meta.goten.com/permissions/regions.batchGet"
            # SKIP lots of other permissions...
          ]
        }
      ]
    },
    {
      "roleBinding": {
        "name": "organizations/testing/roleBindings/fr45545ffffFC",
        "role": "services/iam.edgelq.com/roles/scope-admin",
        "ownedObjects": [
          "-"
        ]
      },
    }
 ]
}

We can use this method to check our RoleBindings in projects and services too. It shows all RoleBindings, including inherited from parent organizations (if exist) and system scope (Role services/iam.edgelq.com/roles/edgelq-public is assigned to all on the system level).

If RoleBinding has ownedObjects, it means we are owners of specified, and we are granted all permissions. Sign - is a wildcard, so we are admins in the whole organization, and we can do whatever we like.

Roles management with conditions

Understanding the Role and its Grants is crucial for effective and secure management of authorization. In the simplest form, The role may look like this:

- name: services/devices.edgelq.com/roles/some-role-name
  displayName: Some Display Name
  category: USER
  grants:
  - permissions:
    - services/devices.edgelq.com/permissions/devices.batchGet
    - services/devices.edgelq.com/permissions/devices.get
    - services/devices.edgelq.com/permissions/devices.list

It allows to read Devices using various methods. Combined with RoleBinding:

- name: projects/test/roleBindings/test
  member: "user:someone@example.com"
  role: services/devices.edgelq.com/roles/some-role-name

Default roles are defined by each service. In core SPEKTRA Edge services, we define all user-facing roles in service iam.edgelq.com.

Project/Organization admins can create their own roles if defualts are not satisfying. Organization and Project administrator will need access to a Service before they are able to create a role with that service permissions.

This will allow a user with a given email to view devices using BatchGet, Get, and List methods in the project test.

However, we can also define some role that allows viewing only a specific device:

- name: services/devices.edgelq.com/roles/single-device-viewer
  displayName: Some Display Name
  category: USER
  scopeParams:
  - name: region
    type: STRING
  - name: device
    type: STRING
  grants:
  - subScope: "regions/{region}/devices/{device}"
    permissions:
    - services/devices.edgelq.com/permissions/devices.batchGet
    - services/devices.edgelq.com/permissions/devices.get

Then we can create RoleBinding:

- name: projects/test/roleBindings/test
  member: "user:someone@example.com"
  role: services/devices.edgelq.com/roles/single-device-viewer
  scopeParams:
  - name: region
    string:
      value: us-west2
  - name: device
    string:
      value: specific-id

This will restrict the user to a specific device: projects/test/regions/us-west2/devices/specific-id. Note that in this case “list” permission makes no sense. Be aware that subScope is APPENDED to the RoleBinding parent name.

We can also give access to multiple devices if we modify the role:

- name: services/devices.edgelq.com/roles/multi-devices-viewer
  scopeParams:
  - name: region
    type: STRING
  - name: device
    type: ARRAY_OF_STRINGS
  ## Other params

RoleBinding could then look like this:

- name: projects/test/roleBindings/test
  member: "user:someone@example.com"
  role: services/devices.edgelq.com/roles/multi-devices-viewer
  scopeParams:
  - name: region
    string:
      value: us-west2
  - name: device
    strings:
      values:
      - specific-id-1
      - specific-id-2

If we wanted to restrict users to some set of devices depending on some condition, we could do something like:

- name: services/devices.edgelq.com/roles/devices-condition-viewer
  displayName: Some Display Name
  category: USER
  scopeParams:
  - name: region
    type: STRING
  - name: tag
    type: STRING
  grants:
  - subScope: "regions/{region}"
    permissions:
    - services/devices.edgelq.com/permissions/devices.batchGet
    - services/devices.edgelq.com/permissions/devices.get
    - services/devices.edgelq.com/permissions/devices.list
    resourceFieldConditions:
    - path: metadata.tags
      value: "{tag}"

The above role will restrict the user to see devices only if their metadata.tags contain a specific tag. Service automatically can detect that field path metadata.tags is an array of strings. If it was a single string, then Role would allow us to see Devices where the tag is EQUAL to the specified value. If you combine ARRAY_OF_STRINGS scope param with the field path containing the array, it will effectively work like CONTAINS ANY.

When it comes to resource field conditions, SPEKTRA Edge Service can automatically detect referenced resources from specified requests. For updates, it will verify two resource states: before and after the update (the user could potentially modify the resource that would match the required condition, but the previous state still matters).

There are more condition types than resource field types, for example, we can reference requests directly:

scopeParams:
- name: service
  type: STRING
grants:
- permissions:
  - services/audit.edgelq.com/permissions/activityLogs.create
  requestFieldConditions:
  - path: activity_logs.service.name
    value: "{service}"

Note that scope params also are used for condition values.

There is a method CreateActivityLogs, which request contains field path activity_logs.service.name, where activity_logs is an array field!

This condition will ensure that for each record in activity_logs array field path service.name has a specified value (both service and name fields are single ones, not arrays).

Note this is a bit of a different behavior compared to resource field conditions: For resources, if the field path contains an array, then it works effectively as CONTAINS condition. In request conditions, each value must satisfy the condition.

TODO: It was more convenient this way, but we will add “allValues” condition separately.

There is also a possibility to use CEL conditions, where we can specify CEL code to execute.

In this example, we allow direct access to internet quality metrics, so a viewing party may request internet quality data per Internet Service Provider for each Province in Japan, but we don’t allow for too narrow filtering or grouping, which could potentially de-anonymize the data, like the exact agent identifier or its location.

First, we need to create iam.edgelq.com/Condition resource:

name: services/watchdog.edgelq.com/conditions/anonymous-time-series
displayName: Watchdog Anonymous Time Series
description: >-
  Inspects Time Series requests to ensure that the user doesn't filter or retrieve private information
  from probe metric labels like name, ID or precise geo-coordinates  
expression: |
  // restrict only Probe/Host Time Series
  (!(request.body.filter.satisfies('resource.type="watchdog.edgelq.com/probe"')) ? true :
   // reduce without identifiable information
   (!request.body.filter.specifies("resource.labels.probe_id") &&
    !request.body.filter.specifies("resource.labels.admin_area3_id") &&
    !request.body.filter.specifies("resource.labels.admin_area3") &&
    !request.body.filter.specifies("resource.labels.admin_area4_id") &&
    !request.body.filter.specifies("resource.labels.admin_area4") &&
    !request.body.filter.specifies("resource.labels.geohash4") &&
    !request.body.filter.specifies("resource.labels.geohash5") &&
    !request.body.filter.specifies("resource.labels.geohash6") &&
    !request.body.filter.specifies("resource.labels.geohash7") &&
    has(request.body.aggregation.cross_series_reducer) &&
    request.body.aggregation.group_by_fields.all(gbf, gbf in [
       "resource.labels.project_id",
       "resource.labels.region_id",
       "resource.labels.probe_group_id",
       "resource.labels.continent",
       "resource.labels.continent_id",
       "resource.labels.country",
       "resource.labels.country_id",
       "resource.labels.admin_area1",
       "resource.labels.admin_area1_id",
       "resource.labels.admin_area2",
       "resource.labels.admin_area2_id",
       "resource.labels.geohash2",
       "resource.labels.geohash3",
       "resource.labels.asn",
       "resource.labels.asn_name",
       "metric.labels.target",
       "metric.labels.target_id",
       "metric.labels.target_group",
       "metric.labels.target_group_id",
       "metric.labels.target_category",
    ])))  
parameterDeclarations: []

CEL Spec: https://github.com/google/cel-spec/blob/v0.7.0/doc/langdef.md.

Then, we can define a Role with grants like:

grants:
- permissions:
  - services/monitoring.edgelq.com/permissions/timeSeries.query
  executableConditions:
  - condition: services/watchdog.edgelq.com/conditions/anonymous-time-series

In the future though (TODO), this condition will be possible to be specified by inline conditions:

scopeParams:
- name: filterCondition
  type: ARRAY_OF_STRINGS
  defaultValues:
  - resource.labels.probe_id
  - ...
  - resource.labels.geohash7
- name: groupByProbeLabels
  type: ARRAY_OF_STRINGS
  defaultValues:
  - resource.labels.project_id
  - ...
  - metric.labels.target_category
grants:
# Access to time series for probes only 
- permissions:
  - services/monitoring.edgelq.com/permissions/timeSeries.query
  requestFieldConditions:
  - path: filter
    doesSatisfy: 'resource.type="watchdog.edgelq.com/probe"'
  - path: filter
    doesNotSpecify: "{filterCondition}"
  - path: aggregation.crossSeriesReducer
    notValue: REDUCE_NONE
  - path: aggregation.groupBy
    valuesAll: "{groupByProbeLabels}"

# Allow for non-probe
- permissions:
  - services/monitoring.edgelq.com/permissions/timeSeries.query
  requestFieldConditions:
  - path: filter
    doesNotSatisfy: 'resource.type="watchdog.edgelq.com/probe"'

SubScopes for collection and single resource actions

When defining subscopes in roles, collection-type actions (list, watch for plural!) must accept subScope without final collection name and resource ID.

For example, all these grants are legal:

# Permissions for non-collection actions and specific device
- subScope: regions/{region}/devices/{device}
  permissions:
  - services/devices.edgelq.com/devices.get
  - services/devices.edgelq.com/devices.batchGet
  - services/devices.edgelq.com/devices.update
  - services/devices.edgelq.com/devices.delete

# Permissions for collection actions and specific region (parent):
- subScope: regions/{region}
  permissions:
  - services/devices.edgelq.com/devices.list
  - services/devices.edgelq.com/devices.create

# Permissions for non-collection actions for specific region
- subScope: regions/{region}
  permissions:
  - services/devices.edgelq.com/devices.get
  - services/devices.edgelq.com/devices.batchGet
  - services/devices.edgelq.com/devices.update
  - services/devices.edgelq.com/devices.delete