metal-stack.io api

Important

Please note that this repository is still in alpha stage. For now, the primary API is still defined in the metal-api project. We will make a special announcement when this repository becomes GA.

This is the V2 API of metal-stack.io to implement MEP-4.

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 and auditing (mainly in interceptors).

Motivational Example

service IPService {
  // Get an 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;
  }
  // Create an ip
  rpc Create(IPServiceCreateRequest) returns (IPServiceCreateResponse) {
    option (project_roles) = PROJECT_ROLE_OWNER;
    option (project_roles) = PROJECT_ROLE_EDITOR;
  }
}

// IPServiceCreateRequest is the request payload for a ip create request
message IPServiceCreateRequest {
  // Network from which the IP should be created
  string network = 1 [(buf.validate.field).string = {
    min_len: 2
    max_len: 128
  }];
  // Project of the ip
  string project = 2 [(buf.validate.field).string.uuid = true];
  // Name of the ip
  optional string name = 3 [(buf.validate.field).string.(metalstack.api.v2.is_name) = true];
  // Description of the ip
  optional string description = 4 [(buf.validate.field).string.(metalstack.api.v2.is_description) = true];
  // IP if given try to create this ip if still available
  optional string ip = 5 [(buf.validate.field).string.ip = true];
  // Machine for which this ip should get created
  optional string machine = 6 [(buf.validate.field).string.uuid = true];
  // Labels to put onto the ip
  optional Labels labels = 7;
  // Type of the IP, ether ephemeral (default), or static
  optional IPType type = 8 [(buf.validate.field).enum.defined_only = true];
  // Addressfamily of the IP to create, defaults to ipv4
  optional IPAddressFamily address_family = 9 [(buf.validate.field).enum.defined_only = true];
}

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
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 visible 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.

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