metalstack.cloud api

This is the API of metalstack.cloud.

Usage examples

Can be found in the examples folder.

Conventions

Method options provide an intuitve and declarative way of providing annotations to service methods. These are used for scoping api-methods, which are getting utilized for authentication, authorization, auditing and payment (mainly in interceptors).

Motivational Example

service IPService {
  // Get a ip
  rpc Get(IPServiceGetRequest) returns (IPServiceGetResponse) {
    option (project_roles) = PROJECT_ROLE_OWNER;
    option (project_roles) = PROJECT_ROLE_EDITOR;
    option (project_roles) = PROJECT_ROLE_VIEWER;
    option (auditing) = AUDITING_EXCLUDED;
  }
  // Allocate a ip
  rpc Allocate(IPServiceAllocateRequest) returns (IPServiceAllocateResponse) {
    option (project_roles) = PROJECT_ROLE_OWNER;
    option (project_roles) = PROJECT_ROLE_EDITOR;
    option (chargeable) = CHARGEABLE_TRUE;
  }
}

message IPServiceAllocateRequest {
  string project = 2 [(buf.validate.field).string = {
    min_len: 2
    max_len: 128
  }];
  string name = 3 [(buf.validate.field).string = {
    min_len: 2
    max_len: 128
  }];
  string description = 4 [(buf.validate.field).string = {max_len: 128}];
  repeated string tags = 8 [(buf.validate.field).repeated.max_items = 100];
  bool static = 9;
}

In this example we can see the motivation behind the method options.

1. Get: can be issued by project owner, editor, viewer and is excluded from auditing
2. Allocate: can be used by project owner, editor and is an service-method which requires deposited payment information
3. Both methods are project-scoped, since they are annotated by a project role -> Request object needs to have the project field in order to specify the target project of the service method

Further explanations are explained in the following:

Auth

These options specify the RBAC of the api-endpoint.

Option	Description	Values	Explanation
TENANT_ROLE_	Specifies the required tenant role	UNSPECIFIED
		OWNER	tenant owner
		EDITOR	tenant editor
		VIEWER	tenant viewer
		GUEST	tenant guest
PROJECT_ROLE_	Specifies the required project role	UNSPECIFIED
		OWNER	project owner
		EDITOR	project editor
		VIEWER	project viewer
ADMIN_ROLE_	Specifies the required admin role	UNSPECIFIED
		EDITOR	admin editor
		VIEWER	admin viewer
VISIBILITY_	Specifies the visibility of the api-endpoint	UNSPECIFIED
		PUBLIC	api-method is visbile to public, a token is not needed
		SELF	api-method is scoped to owner resources

Important

Every operation needs at least an option, which references the scope of the request: ROLE or VISIBILITY

Caution

If we use a Tenant or Project role, the request will be respectively scoped as Tenant or Project request. Tenant-Requests must have the field login, which is the tenant id and specifies the tenant on which the service-method is scoped. Project-Requests must have the field project, which is the project id and specifies the project on which the service-method is scoped.

Payment

Some api-methods are associated with payment and will result in costs. In order to use these kind of operations the user must have deposited its payment information. If the payment information are not deposited the user is not allowed to issue these actions.

Option	Description	Values	Explanation
CHARGEABLE_	Specifies if the api-endpoint is chargeable	UNSPECIFIED
		TRUE	api-method is associated with payment and requires deposited payment infos
		FALSE	api-method is not associated with payment

Auditing

For traceability we require to store audit-logs.

Option	Description	Values	Explanation
AUDITING_	Specifies if the api-endpoint is audited	UNSPECIFIED	DEFAULT: included
		INCLUDED	operation is audited
		EXCLUDED	operation is not audited