feat: add system api proto (#3294)

* feat: add system api proto

* Update proto/zitadel/instance.proto

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* Update proto/zitadel/instance.proto

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* Update proto/zitadel/instance.proto

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* feat: add system api proto

* feat: add system api proto

* feat: add system api proto

* feat: add system api proto

* generate grpc

* feat: remove region from system proto

* fix: remove metrics endpoint

* fix: add md file

* rebuild proto

Co-authored-by: Livio Amstutz <livio.a@gmail.com>
This commit is contained in:
Fabi
2022-03-22 08:47:18 +01:00
committed by GitHub
parent 5132ebe07c
commit 9e13b70a3d
8 changed files with 1454 additions and 2 deletions

View File

@@ -0,0 +1,104 @@
syntax = "proto3";
import "zitadel/object.proto";
import "validate/validate.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
package zitadel.instance.v1;
option go_package ="github.com/caos/zitadel/pkg/grpc/instance";
message Instance {
string id = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"69629023906488334\""
}
];
zitadel.v1.ObjectDetails details = 2;
State state = 3 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "current state of the instance";
}
];
string generated_domain = 4 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"organization.zitadel.com\"";
}
];
repeated string custom_domains = 5 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "[\"zitadel.com\", \"zitadel.cloud\", \"zitadel.ch\"]";
}
];
string name = 6 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"ZITADEL\"";
}
];
string version = 7 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"v1.0.0\"";
}
];
}
enum State {
STATE_UNSPECIFIED = 0;
STATE_CREATING = 1;
STATE_RUNNING = 2;
STATE_STOPPING = 3;
STATE_STOPPED = 4;
}
message Query {
oneof query {
option (validate.required) = true;
IdQuery id_query = 1;
DomainsQuery domains_query = 2;
StateQuery state_query = 3;
}
}
//IdQuery is always equals
message IdQuery {
string id = 1 [
(validate.rules).string = {max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "4820840938402429";
}
];
}
message DomainsQuery {
repeated string domains = 1 [
(validate.rules).string = {max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"caos.ch\"";
}
];
zitadel.v1.ListQueryMethod method = 2 [
(validate.rules).enum.defined_only = true,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "defines which list equality method is used";
}
];
}
//StateQuery is always equals
message StateQuery {
State state = 1 [
(validate.rules).enum.defined_only = true,
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "current state of the instance";
}
];
}
enum FieldName {
FIELD_NAME_UNSPECIFIED = 0;
FIELD_NAME_ID = 1;
FIELD_NAME_GENERATED_DOMAIN = 2;
FIELD_NAME_NAME = 3;
FIELD_NAME_CREATION_DATE = 4;
}

View File

@@ -85,3 +85,8 @@ enum TextQueryMethod {
TEXT_QUERY_METHOD_ENDS_WITH = 6;
TEXT_QUERY_METHOD_ENDS_WITH_IGNORE_CASE = 7;
}
enum ListQueryMethod {
LIST_QUERY_METHOD_IN = 0;
}

524
proto/zitadel/system.proto Normal file
View File

@@ -0,0 +1,524 @@
syntax = "proto3";
import "zitadel/object.proto";
import "zitadel/options.proto";
import "zitadel/instance.proto";
import "zitadel/text.proto";
import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
import "validate/validate.proto";
package zitadel.system.v1;
option go_package ="github.com/caos/zitadel/pkg/grpc/system";
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
info: {
title: "System API";
version: "1.0";
description: "This API is intended to configure and manage the different tenants whithin ZITADEL.";
contact:{
name: "CAOS developers of ZITADEL"
url: "https://zitadel.ch"
email: "hi@zitadel.ch"
}
license: {
name: "Apache 2.0",
url: "https://github.com/caos/zitadel/blob/main/LICENSE";
};
};
schemes: HTTPS;
schemes: HTTP;
consumes: "application/json";
consumes: "application/grpc";
produces: "application/json";
produces: "application/grpc";
consumes: "application/grpc-web+proto";
produces: "application/grpc-web+proto";
host: "api.zitadel.ch";
base_path: "/system/v1";
external_docs: {
description: "Detailed information about ZITADEL",
url: "https://docs.zitadel.ch"
}
responses: {
key: "403";
value: {
description: "Returned when the user does not have permission to access the resource.";
schema: {
json_schema: {
ref: "#/definitions/rpcStatus";
}
}
}
}
responses: {
key: "404";
value: {
description: "Returned when the resource does not exist.";
schema: {
json_schema: {
ref: "#/definitions/rpcStatus";
}
}
}
}
};
service SystemService {
//Indicates if ZITADEL is running.
// It respondes as soon as ZITADEL started
rpc Healthz(HealthzRequest) returns (HealthzResponse) {
option (google.api.http) = {
get: "/healthz";
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
tags: "probes";
responses: {
key: "200";
value: {
description: "ZITADEL started";
};
}
responses: {
key: "default";
value: {
description: "ZITADEL NOT started yet";
};
}
};
}
// Returns a list of ZITADEL instances/tenants
rpc ListInstances(ListInstancesRequest) returns (ListInstancesResponse) {
option (google.api.http) = {
post: "/instances"
body: "*"
};
}
// Returns the detail of an instance
rpc GetInstance(GetInstanceRequest) returns (GetInstanceResponse) {
option (google.api.http) = {
get: "/instances/{id}";
};
}
// Creates a new instance with all needed setup data
// This might take some time
rpc AddInstance(AddInstanceRequest) returns (AddInstanceResponse) {
option (google.api.http) = {
post: "/instances"
body: "*"
};
}
// Removes a instances
// This might take some time
rpc RemoveInstance(RemoveInstanceRequest) returns (RemoveInstanceResponse) {
option (google.api.http) = {
delete: "/instances/{id}"
};
}
// Returns the usage metrics of an instance
rpc GetUsage(GetUsageRequest) returns (GetUsageResponse) {
option (google.api.http) = {
get: "/instances/{id}/usage";
};
}
// Returns the domain of an instance
rpc GetGeneratedDomain(GetGeneratedDomainRequest) returns (GetGeneratedDomainResponse) {
option (google.api.http) = {
get: "/instances/{id}/domains/generated";
};
}
// Returns the custom domains of an instance
rpc GetCustomDomains(GetCustomDomainsRequest) returns (GetCustomDomainsResponse) {
option (google.api.http) = {
get: "/instances/{id}/domains/custom";
};
}
// Returns the domain of an instance
rpc AddCustomDomain(AddCustomDomainRequest) returns (AddCustomDomainResponse) {
option (google.api.http) = {
post: "/instances/{id}/domains/custom";
body: "*"
};
}
//Returns all stored read models of ZITADEL
// views are used for search optimisation and optimise request latencies
// they represent the delta of the event happend on the objects
rpc ListViews(ListViewsRequest) returns (ListViewsResponse) {
option (google.api.http) = {
post: "/views/_search";
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
tags: "views";
external_docs: {
url: "https://docs.zitadel.ch/concepts#Software_Architecture";
description: "details of ZITADEL's event driven software concepts";
};
responses: {
key: "200";
value: {
description: "Views for query operations";
};
};
};
}
//Truncates the delta of the change stream
// be carefull with this function because ZITADEL has to
// recompute the deltas after they got cleared.
// Search requests will return wrong results until all deltas are recomputed
rpc ClearView(ClearViewRequest) returns (ClearViewResponse) {
option (google.api.http) = {
post: "/views/{database}/{view_name}";
};
option (zitadel.v1.auth_option) = {
permission: "iam.write";
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
tags: "views";
external_docs: {
url: "https://docs.zitadel.ch/concepts#Software_Architecture";
description: "details of ZITADEL's event driven software concepts";
};
responses: {
key: "200";
value: {
description: "View cleared";
};
};
};
}
//Returns event descriptions which cannot be processed.
// It's possible that some events need some retries.
// For example if the SMTP-API wasn't able to send an email at the first time
rpc ListFailedEvents(ListFailedEventsRequest) returns (ListFailedEventsResponse) {
option (google.api.http) = {
post: "/failedevents/_search";
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
tags: "failed events";
external_docs: {
url: "https://docs.zitadel.ch/concepts#Software_Architecture";
description: "details of ZITADEL's event driven software concepts";
};
responses: {
key: "200";
value: {
description: "Events which were not processed by the views";
};
};
};
}
//Deletes the event from failed events view.
// the event is not removed from the change stream
// This call is usefull if the system was able to process the event later.
// e.g. if the second try of sending an email was successful. the first try produced a
// failed event. You can find out if it worked on the `failure_count`
rpc RemoveFailedEvent(RemoveFailedEventRequest) returns (RemoveFailedEventResponse) {
option (google.api.http) = {
delete: "/failedevents/{database}/{view_name}/{failed_sequence}";
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
tags: "failed events";
external_docs: {
url: "https://docs.zitadel.ch/concepts#Software_Architecture";
description: "details of ZITADEL's event driven software concepts";
};
responses: {
key: "200";
value: {
description: "Events removed from the list";
};
};
responses: {
key: "400";
value: {
description: "failed event not found";
schema: {
json_schema: {
ref: "#/definitions/rpcStatus";
};
};
};
};
};
}
}
//This is an empty request
message HealthzRequest {}
//This is an empty response
message HealthzResponse {}
message ListInstancesRequest {
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
json_schema: {
description: "Search query for lists";
required: ["query"]
};
};
//list limitations and ordering
zitadel.v1.ListQuery query = 1;
// the field the result is sorted
zitadel.instance.v1.FieldName sorting_column = 2;
//criterias the client is looking for
repeated zitadel.instance.v1.Query queries = 3;
}
message ListInstancesResponse {
zitadel.v1.ListDetails details = 1;
zitadel.instance.v1.FieldName sorting_column = 2;
repeated zitadel.instance.v1.Instance result = 3;
}
message GetInstanceRequest {
string id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
}
message GetInstanceResponse {
zitadel.instance.v1.Instance instance = 1;
}
message AddInstanceRequest {
string instance_name = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
string first_org_name = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
string custom_domain = 3 [(validate.rules).string = {max_len: 200}];
string owner_first_name = 4 [(validate.rules).string = {min_len: 1, max_len: 200}];
string owner_last_name = 5 [(validate.rules).string = {min_len: 1, max_len: 200}];
string owner_email = 6 [(validate.rules).string = {min_len: 1, max_len: 200}];
string owner_username = 7 [(validate.rules).string = {min_len: 1, max_len: 200}];
string password = 8 [(validate.rules).string = {min_len: 1, max_len: 200}];
uint64 request_limit = 9;
uint64 action_mins_limit = 10;
}
message AddInstanceResponse {
string id = 1;
}
message RemoveInstanceRequest {
string id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
}
message RemoveInstanceResponse {
zitadel.v1.ObjectDetails details = 1;
}
message GetUsageRequest {
string id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
}
message GetUsageResponse {
zitadel.v1.ObjectDetails details = 1;
uint64 executed_requests = 2;
uint64 executed_action_mins = 3;
}
message GetGeneratedDomainRequest {
string id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
}
message GetGeneratedDomainResponse {
zitadel.v1.ObjectDetails details = 1;
string domain = 2;
}
message GetCustomDomainsRequest {
string id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
}
message GetCustomDomainsResponse {
zitadel.v1.ObjectDetails details = 1;
repeated string domains = 2;
}
message AddCustomDomainRequest {
string id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
string custom_domain = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
}
message AddCustomDomainResponse {
zitadel.v1.ObjectDetails details = 1;
}
message ChangeSubscriptionRequest {
string domain = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
string subscription_name = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
uint64 request_limit = 3;
uint64 action_mins_limit = 4;
}
message ChangeSubscriptionResponse {
zitadel.v1.ObjectDetails details = 1;
}
//This is an empty request
message ListViewsRequest {}
message ListViewsResponse {
//TODO: list details
repeated View result = 1;
}
message ClearViewRequest {
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
json_schema: {
required: ["database", "view_name"]
};
};
string database = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"adminapi\"";
min_length: 1;
max_length: 200;
}
];
string view_name = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"iam_members\"";
min_length: 1;
max_length: 200;
}
];
}
//This is an empty response
message ClearViewResponse {}
//This is an empty request
message ListFailedEventsRequest {}
message ListFailedEventsResponse {
//TODO: list details
repeated FailedEvent result = 1;
}
message RemoveFailedEventRequest {
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
json_schema: {
required: ["database", "view_name", "failed_sequence"]
};
};
string database = 1 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"adminapi\"";
min_length: 1;
max_length: 200;
}
];
string view_name = 2 [
(validate.rules).string = {min_len: 1, max_len: 200},
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"iam_members\"";
min_length: 1;
max_length: 200;
}
];
uint64 failed_sequence = 3 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"9823758\"";
}
];
}
//This is an empty response
message RemoveFailedEventResponse {}
message View {
string database = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"adminapi\"";
}
];
string view_name = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"iam_members\"";
}
];
uint64 processed_sequence = 3 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"9823758\"";
}
];
google.protobuf.Timestamp event_timestamp = 4 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"2019-04-01T08:45:00.000000Z\"";
description: "The timestamp the event occured";
}
]; // The timestamp the event occured
google.protobuf.Timestamp last_successful_spooler_run = 5 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "The timestamp the event occured";
}
];
string instance = 6 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"840498034930840\"";
}
];
}
message FailedEvent {
string database = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"adminapi\"";
}
];
string view_name = 2 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"iam_members\"";
}
];
uint64 failed_sequence = 3 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"9823759\"";
}
];
uint64 failure_count = 4 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"5\"";
}
];
string error_message = 5 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
example: "\"ID=EXAMP-ID3ER Message=Example message\"";
}
];
}