diff --git a/api/external/secrets/secrets.pb.go b/api/external/secrets/secrets.pb.go index dc70719db89..72364c5dcc8 100644 --- a/api/external/secrets/secrets.pb.go +++ b/api/external/secrets/secrets.pb.go @@ -29,6 +29,7 @@ var _ = math.Inf // proto package needs to be updated. const _ = proto.ProtoPackageIsVersion3 // please upgrade the proto package +// Return the results in ascending or descending order. type Query_OrderType int32 const ( @@ -117,6 +118,7 @@ func (m *DeleteResponse) XXX_DiscardUnknown() { var xxx_messageInfo_DeleteResponse proto.InternalMessageInfo type Id struct { + // Unique node ID (UUID). Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -156,14 +158,18 @@ func (m *Id) GetId() string { } type Query struct { - Filters []*query.Filter `protobuf:"bytes,20,rep,name=filters,proto3" json:"filters,omitempty"` - Order Query_OrderType `protobuf:"varint,21,opt,name=order,proto3,enum=chef.automate.api.secrets.Query_OrderType" json:"order,omitempty"` - Sort string `protobuf:"bytes,22,opt,name=sort,proto3" json:"sort,omitempty"` - Page int32 `protobuf:"varint,23,opt,name=page,proto3" json:"page,omitempty"` - PerPage int32 `protobuf:"varint,24,opt,name=per_page,json=perPage,proto3" json:"per_page,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // Use filters to limit the set of secrets. + Filters []*query.Filter `protobuf:"bytes,20,rep,name=filters,proto3" json:"filters,omitempty"` + Order Query_OrderType `protobuf:"varint,21,opt,name=order,proto3,enum=chef.automate.api.secrets.Query_OrderType" json:"order,omitempty"` + // Sort the results on a specific field. + Sort string `protobuf:"bytes,22,opt,name=sort,proto3" json:"sort,omitempty"` + // The number of result pages to return. + Page int32 `protobuf:"varint,23,opt,name=page,proto3" json:"page,omitempty"` + // The number of results on each page. + PerPage int32 `protobuf:"varint,24,opt,name=per_page,json=perPage,proto3" json:"per_page,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *Query) Reset() { *m = Query{} } @@ -227,15 +233,21 @@ func (m *Query) GetPerPage() int32 { } type Secret struct { - Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"` - Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"` - Type string `protobuf:"bytes,3,opt,name=type,proto3" json:"type,omitempty"` - LastModified *timestamp.Timestamp `protobuf:"bytes,20,opt,name=last_modified,json=lastModified,proto3" json:"last_modified,omitempty"` - Tags []*query.Kv `protobuf:"bytes,21,rep,name=tags,proto3" json:"tags,omitempty"` - Data []*query.Kv `protobuf:"bytes,22,rep,name=data,proto3" json:"data,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // Unique node ID (UUID). + Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"` + // User-specified name for the secret. + Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"` + // Type of credential: ssh, winrm, sudo, aws, azure, gcp, service_now + Type string `protobuf:"bytes,3,opt,name=type,proto3" json:"type,omitempty"` + // Timestamp denoting when the secret was last modified. + LastModified *timestamp.Timestamp `protobuf:"bytes,20,opt,name=last_modified,json=lastModified,proto3" json:"last_modified,omitempty"` + // Tags to associate with the secret. + Tags []*query.Kv `protobuf:"bytes,21,rep,name=tags,proto3" json:"tags,omitempty"` + // Secret data, where the kv structs for the credential data live. + Data []*query.Kv `protobuf:"bytes,22,rep,name=data,proto3" json:"data,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *Secret) Reset() { *m = Secret{} } @@ -306,11 +318,13 @@ func (m *Secret) GetData() []*query.Kv { } type Secrets struct { - Secrets []*Secret `protobuf:"bytes,1,rep,name=secrets,proto3" json:"secrets,omitempty"` - Total int32 `protobuf:"varint,20,opt,name=total,proto3" json:"total,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + // List of secrets. + Secrets []*Secret `protobuf:"bytes,1,rep,name=secrets,proto3" json:"secrets,omitempty"` + // Total count of secrets + Total int32 `protobuf:"varint,20,opt,name=total,proto3" json:"total,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *Secrets) Reset() { *m = Secrets{} } @@ -431,10 +445,111 @@ const _ = grpc.SupportPackageIsVersion6 // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://godoc.org/google.golang.org/grpc#ClientConn.NewStream. type SecretsServiceClient interface { + // + //Create a secret + // + //Creates a secret. Requires values for name, type, and data. + // + //Supported types: ssh, winrm, sudo, aws, azure, gcp, service_now + //Supported keys by type: + //ssh: username, password, key + //winrm: username, password + //sudo: username, password + //service_now: username, password + //aws: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN + //azure: AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID + //gcp: GOOGLE_CREDENTIALS_JSON + // + //Example: + //``` + //{ + //"name": "my ssh secret", + //"type": "ssh", + //"data": [ + //{ "key": "username", "value": "vagrant" }, + //{ "key": "password", "value": "vagrant"} + //] + //} + //``` + // + //Authorization Action: + //``` + //secrets:secrets:create + //``` Create(ctx context.Context, in *Secret, opts ...grpc.CallOption) (*Id, error) + // + //Read a secret + // + //Reads a secret given the ID of the secret. + //Note that the secret information (password and key values) will not be returned by the API, as a safety measure. + // + //Authorization Action: + //``` + //secrets:secrets:get + //``` Read(ctx context.Context, in *Id, opts ...grpc.CallOption) (*Secret, error) + // + //Update a secret + // + //Updates a secret. + //This is a PATCH operation, meaning the details sent in will override/replace those stored in the DB. + //Secret information that is not in the body of the request will persist. + // + //Example: + //``` + //given a credential with a username and password, a user could update the password by passing in the following body, + //and the name of the secret as well as the username for the secret be unchanged: + // + //{ + //"id": "525c013a-2ab3-4e6f-9005-51bc620e9157", + //"data": [ + //{ "key": "password", "value": "new-value"} + //] + //} + //``` + // + //Authorization Action: + //``` + //secrets:secrets:update + //``` Update(ctx context.Context, in *Secret, opts ...grpc.CallOption) (*UpdateResponse, error) + // + //Delete a secret + // + //Deletes a secret given the ID of the secret. + //Note that any nodes that were using the secret will no longer be associated with the deleted secret. + // + //Authorization Action: + //``` + //secrets:secrets:delete + //``` Delete(ctx context.Context, in *Id, opts ...grpc.CallOption) (*DeleteResponse, error) + // + //List and filter secrets + // + //Makes a list of secrets. + //Supports filtering, pagination, and sorting. + //Adding a filter narrows the list of secrets to only those that match the filter or filters. + //Supported filters: type + //Supported sort types: name, type, last modified + // + //Example: + //``` + //{ + //"sort": "type", + //"order": "ASC", + //"filters": [ + //{ "key": "type", "values": ["ssh","winrm","sudo"] } + //], + //"page":1, + //"per_page":100 + //} + //``` + // + //Authorization Action: + //``` + //secrets:secrets:list + //``` List(ctx context.Context, in *Query, opts ...grpc.CallOption) (*Secrets, error) } @@ -493,10 +608,111 @@ func (c *secretsServiceClient) List(ctx context.Context, in *Query, opts ...grpc // SecretsServiceServer is the server API for SecretsService service. type SecretsServiceServer interface { + // + //Create a secret + // + //Creates a secret. Requires values for name, type, and data. + // + //Supported types: ssh, winrm, sudo, aws, azure, gcp, service_now + //Supported keys by type: + //ssh: username, password, key + //winrm: username, password + //sudo: username, password + //service_now: username, password + //aws: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN + //azure: AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID + //gcp: GOOGLE_CREDENTIALS_JSON + // + //Example: + //``` + //{ + //"name": "my ssh secret", + //"type": "ssh", + //"data": [ + //{ "key": "username", "value": "vagrant" }, + //{ "key": "password", "value": "vagrant"} + //] + //} + //``` + // + //Authorization Action: + //``` + //secrets:secrets:create + //``` Create(context.Context, *Secret) (*Id, error) + // + //Read a secret + // + //Reads a secret given the ID of the secret. + //Note that the secret information (password and key values) will not be returned by the API, as a safety measure. + // + //Authorization Action: + //``` + //secrets:secrets:get + //``` Read(context.Context, *Id) (*Secret, error) + // + //Update a secret + // + //Updates a secret. + //This is a PATCH operation, meaning the details sent in will override/replace those stored in the DB. + //Secret information that is not in the body of the request will persist. + // + //Example: + //``` + //given a credential with a username and password, a user could update the password by passing in the following body, + //and the name of the secret as well as the username for the secret be unchanged: + // + //{ + //"id": "525c013a-2ab3-4e6f-9005-51bc620e9157", + //"data": [ + //{ "key": "password", "value": "new-value"} + //] + //} + //``` + // + //Authorization Action: + //``` + //secrets:secrets:update + //``` Update(context.Context, *Secret) (*UpdateResponse, error) + // + //Delete a secret + // + //Deletes a secret given the ID of the secret. + //Note that any nodes that were using the secret will no longer be associated with the deleted secret. + // + //Authorization Action: + //``` + //secrets:secrets:delete + //``` Delete(context.Context, *Id) (*DeleteResponse, error) + // + //List and filter secrets + // + //Makes a list of secrets. + //Supports filtering, pagination, and sorting. + //Adding a filter narrows the list of secrets to only those that match the filter or filters. + //Supported filters: type + //Supported sort types: name, type, last modified + // + //Example: + //``` + //{ + //"sort": "type", + //"order": "ASC", + //"filters": [ + //{ "key": "type", "values": ["ssh","winrm","sudo"] } + //], + //"page":1, + //"per_page":100 + //} + //``` + // + //Authorization Action: + //``` + //secrets:secrets:list + //``` List(context.Context, *Query) (*Secrets, error) } diff --git a/api/external/secrets/secrets.proto b/api/external/secrets/secrets.proto index a7ca7093679..4d445bd05ca 100644 --- a/api/external/secrets/secrets.proto +++ b/api/external/secrets/secrets.proto @@ -14,6 +14,38 @@ import "components/automate-grpc/protoc-gen-policy/iam/annotations.proto"; import "api/external/common/query/parameters.proto"; service SecretsService { + /* + Create a secret + + Creates a secret. Requires values for name, type, and data. + + Supported types: ssh, winrm, sudo, aws, azure, gcp, service_now + Supported keys by type: + ssh: username, password, key + winrm: username, password + sudo: username, password + service_now: username, password + aws: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN + azure: AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID + gcp: GOOGLE_CREDENTIALS_JSON + + Example: + ``` + { + "name": "my ssh secret", + "type": "ssh", + "data": [ + { "key": "username", "value": "vagrant" }, + { "key": "password", "value": "vagrant"} + ] + } + ``` + + Authorization Action: + ``` + secrets:secrets:create + ``` + */ rpc Create(Secret) returns (Id) { option (google.api.http) = { post: "/secrets" @@ -28,6 +60,18 @@ service SecretsService { action: "secrets:secrets:create" }; }; + + /* + Read a secret + + Reads a secret given the ID of the secret. + Note that the secret information (password and key values) will not be returned by the API, as a safety measure. + + Authorization Action: + ``` + secrets:secrets:get + ``` + */ rpc Read(Id) returns (Secret) { option (google.api.http) = { get: "/secrets/id/{id}" @@ -41,6 +85,32 @@ service SecretsService { action: "secrets:secrets:get" }; }; + + /* + Update a secret + + Updates a secret. + This is a PATCH operation, meaning the details sent in will override/replace those stored in the DB. + Secret information that is not in the body of the request will persist. + + Example: + ``` + given a credential with a username and password, a user could update the password by passing in the following body, + and the name of the secret as well as the username for the secret be unchanged: + + { + "id": "525c013a-2ab3-4e6f-9005-51bc620e9157", + "data": [ + { "key": "password", "value": "new-value"} + ] + } + ``` + + Authorization Action: + ``` + secrets:secrets:update + ``` + */ rpc Update(Secret) returns (UpdateResponse) { option (google.api.http) = { patch: "/secrets/id/{id}" @@ -55,6 +125,18 @@ service SecretsService { action: "secrets:secrets:update" }; }; + + /* + Delete a secret + + Deletes a secret given the ID of the secret. + Note that any nodes that were using the secret will no longer be associated with the deleted secret. + + Authorization Action: + ``` + secrets:secrets:delete + ``` + */ rpc Delete(Id) returns (DeleteResponse) { option (google.api.http) = { delete: "/secrets/id/{id}" @@ -68,6 +150,34 @@ service SecretsService { action: "secrets:secrets:delete" }; }; + + /* + List and filter secrets + + Makes a list of secrets. + Supports filtering, pagination, and sorting. + Adding a filter narrows the list of secrets to only those that match the filter or filters. + Supported filters: type + Supported sort types: name, type, last modified + + Example: + ``` + { + "sort": "type", + "order": "ASC", + "filters": [ + { "key": "type", "values": ["ssh","winrm","sudo"] } + ], + "page":1, + "per_page":100 + } + ``` + + Authorization Action: + ``` + secrets:secrets:list + ``` + */ rpc List(Query) returns (Secrets) { option (google.api.http) = { post: "/secrets/search" @@ -87,32 +197,47 @@ service SecretsService { message UpdateResponse {} message DeleteResponse {} + message Id { + // Unique node ID (UUID). string id = 1; } message Query { + // Use filters to limit the set of secrets. repeated chef.automate.api.common.query.Filter filters = 20; + // Return the results in ascending or descending order. enum OrderType { ASC = 0; DESC = 1; } OrderType order = 21; + // Sort the results on a specific field. string sort = 22; + // The number of result pages to return. int32 page = 23; + // The number of results on each page. int32 per_page = 24; } message Secret { + // Unique node ID (UUID). string id = 1; + // User-specified name for the secret. string name = 2; + // Type of credential: ssh, winrm, sudo, aws, azure, gcp, service_now string type = 3; + // Timestamp denoting when the secret was last modified. google.protobuf.Timestamp last_modified = 20; + // Tags to associate with the secret. repeated chef.automate.api.common.query.Kv tags = 21; + // Secret data, where the kv structs for the credential data live. repeated chef.automate.api.common.query.Kv data = 22; } message Secrets { + // List of secrets. repeated Secret secrets = 1; + // Total count of secrets int32 total = 20; } diff --git a/api/external/secrets/secrets.swagger.json b/api/external/secrets/secrets.swagger.json index 35cb64e51f1..dbaa831a73c 100644 --- a/api/external/secrets/secrets.swagger.json +++ b/api/external/secrets/secrets.swagger.json @@ -13,6 +13,8 @@ "paths": { "/secrets": { "post": { + "summary": "Create a secret", + "description": "Creates a secret. Requires values for name, type, and data.\n\nSupported types: ssh, winrm, sudo, aws, azure, gcp, service_now\nSupported keys by type: \nssh: username, password, key\nwinrm: username, password\nsudo: username, password\nservice_now: username, password\naws: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN\nazure: AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID\ngcp: GOOGLE_CREDENTIALS_JSON\n\nExample:\n```\n{\n\"name\": \"my ssh secret\",\n\"type\": \"ssh\",\n\"data\": [\n{ \"key\": \"username\", \"value\": \"vagrant\" },\n{ \"key\": \"password\", \"value\": \"vagrant\"} \n]\n}\n```\n\nAuthorization Action:\n```\nsecrets:secrets:create\n```", "operationId": "Create", "responses": { "200": { @@ -39,6 +41,8 @@ }, "/secrets/id/{id}": { "get": { + "summary": "Read a secret", + "description": "Reads a secret given the ID of the secret.\nNote that the secret information (password and key values) will not be returned by the API, as a safety measure.\n\nAuthorization Action:\n```\nsecrets:secrets:get\n```", "operationId": "Read", "responses": { "200": { @@ -51,6 +55,7 @@ "parameters": [ { "name": "id", + "description": "Unique node ID (UUID).", "in": "path", "required": true, "type": "string" @@ -61,6 +66,8 @@ ] }, "delete": { + "summary": "Delete a secret", + "description": "Deletes a secret given the ID of the secret.\nNote that any nodes that were using the secret will no longer be associated with the deleted secret.\n\nAuthorization Action:\n```\nsecrets:secrets:delete\n```", "operationId": "Delete", "responses": { "200": { @@ -73,6 +80,7 @@ "parameters": [ { "name": "id", + "description": "Unique node ID (UUID).", "in": "path", "required": true, "type": "string" @@ -83,6 +91,8 @@ ] }, "patch": { + "summary": "Update a secret", + "description": "Updates a secret. \nThis is a PATCH operation, meaning the details sent in will override/replace those stored in the DB.\nSecret information that is not in the body of the request will persist.\n\nExample:\n```\ngiven a credential with a username and password, a user could update the password by passing in the following body, \nand the name of the secret as well as the username for the secret be unchanged:\n\n{\n\"id\": \"525c013a-2ab3-4e6f-9005-51bc620e9157\",\n\"data\": [\n{ \"key\": \"password\", \"value\": \"new-value\"} \n]\n}\n```\n\nAuthorization Action:\n```\nsecrets:secrets:update\n```", "operationId": "Update", "responses": { "200": { @@ -95,6 +105,7 @@ "parameters": [ { "name": "id", + "description": "Unique node ID (UUID).", "in": "path", "required": true, "type": "string" @@ -115,6 +126,8 @@ }, "/secrets/search": { "post": { + "summary": "List and filter secrets", + "description": "Makes a list of secrets.\nSupports filtering, pagination, and sorting.\nAdding a filter narrows the list of secrets to only those that match the filter or filters.\nSupported filters: type\nSupported sort types: name, type, last modified\n\nExample:\n```\n{\n\"sort\": \"type\",\n\"order\": \"ASC\",\n\"filters\": [\n{ \"key\": \"type\", \"values\": [\"ssh\",\"winrm\",\"sudo\"] }\n],\n\"page\":1,\n\"per_page\":100\n}\n```\n\nAuthorization Action:\n```\nsecrets:secrets:list\n```", "operationId": "List", "responses": { "200": { @@ -182,7 +195,8 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique node ID (UUID)." } } }, @@ -193,21 +207,25 @@ "type": "array", "items": { "$ref": "#/definitions/chef.automate.api.common.query.Filter" - } + }, + "description": "Use filters to limit the set of secrets." }, "order": { "$ref": "#/definitions/chef.automate.api.secrets.Query.OrderType" }, "sort": { - "type": "string" + "type": "string", + "description": "Sort the results on a specific field." }, "page": { "type": "integer", - "format": "int32" + "format": "int32", + "description": "The number of result pages to return." }, "per_page": { "type": "integer", - "format": "int32" + "format": "int32", + "description": "The number of results on each page." } } }, @@ -217,35 +235,42 @@ "ASC", "DESC" ], - "default": "ASC" + "default": "ASC", + "description": "Return the results in ascending or descending order." }, "chef.automate.api.secrets.Secret": { "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique node ID (UUID)." }, "name": { - "type": "string" + "type": "string", + "description": "User-specified name for the secret." }, "type": { - "type": "string" + "type": "string", + "title": "Type of credential: ssh, winrm, sudo, aws, azure, gcp, service_now" }, "last_modified": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp denoting when the secret was last modified." }, "tags": { "type": "array", "items": { "$ref": "#/definitions/chef.automate.api.common.query.Kv" - } + }, + "description": "Tags to associate with the secret." }, "data": { "type": "array", "items": { "$ref": "#/definitions/chef.automate.api.common.query.Kv" - } + }, + "description": "Secret data, where the kv structs for the credential data live." } } }, @@ -256,11 +281,13 @@ "type": "array", "items": { "$ref": "#/definitions/chef.automate.api.secrets.Secret" - } + }, + "description": "List of secrets." }, "total": { "type": "integer", - "format": "int32" + "format": "int32", + "title": "Total count of secrets" } } }, diff --git a/components/automate-chef-io/data/docs/api-static/03-tags.swagger.json b/components/automate-chef-io/data/docs/api-static/03-tags.swagger.json index f1af6283239..87eb718c931 100644 --- a/components/automate-chef-io/data/docs/api-static/03-tags.swagger.json +++ b/components/automate-chef-io/data/docs/api-static/03-tags.swagger.json @@ -12,6 +12,10 @@ "name": "Node Management", "tags": ["NodeManagerService", "NodesService"] }, + { + "name": "Secrets", + "tags": ["SecretsService"] + }, { "name": "Applications", "tags": ["service_groups", "retention"] @@ -31,6 +35,7 @@ { "name": "StatsService", "x-displayName": "Stats" }, { "name": "ConfigMgmt", "x-displayName": "Nodes" }, { "name": "NodesService", "x-displayName": "Managed Nodes" }, + { "name": "SecretsService", "x-displayName": "Secrets" }, { "name": "service_groups", "x-displayName": "Service Groups and Services" }, { "name": "retention", "x-displayName": "Service Management" }, { "name": "NodeManagerService", "x-displayName": "Node Managers" }, diff --git a/components/automate-chef-io/data/docs/api_chef_automate/secrets/secrets.swagger.json b/components/automate-chef-io/data/docs/api_chef_automate/secrets/secrets.swagger.json index 35cb64e51f1..dbaa831a73c 100644 --- a/components/automate-chef-io/data/docs/api_chef_automate/secrets/secrets.swagger.json +++ b/components/automate-chef-io/data/docs/api_chef_automate/secrets/secrets.swagger.json @@ -13,6 +13,8 @@ "paths": { "/secrets": { "post": { + "summary": "Create a secret", + "description": "Creates a secret. Requires values for name, type, and data.\n\nSupported types: ssh, winrm, sudo, aws, azure, gcp, service_now\nSupported keys by type: \nssh: username, password, key\nwinrm: username, password\nsudo: username, password\nservice_now: username, password\naws: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN\nazure: AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID\ngcp: GOOGLE_CREDENTIALS_JSON\n\nExample:\n```\n{\n\"name\": \"my ssh secret\",\n\"type\": \"ssh\",\n\"data\": [\n{ \"key\": \"username\", \"value\": \"vagrant\" },\n{ \"key\": \"password\", \"value\": \"vagrant\"} \n]\n}\n```\n\nAuthorization Action:\n```\nsecrets:secrets:create\n```", "operationId": "Create", "responses": { "200": { @@ -39,6 +41,8 @@ }, "/secrets/id/{id}": { "get": { + "summary": "Read a secret", + "description": "Reads a secret given the ID of the secret.\nNote that the secret information (password and key values) will not be returned by the API, as a safety measure.\n\nAuthorization Action:\n```\nsecrets:secrets:get\n```", "operationId": "Read", "responses": { "200": { @@ -51,6 +55,7 @@ "parameters": [ { "name": "id", + "description": "Unique node ID (UUID).", "in": "path", "required": true, "type": "string" @@ -61,6 +66,8 @@ ] }, "delete": { + "summary": "Delete a secret", + "description": "Deletes a secret given the ID of the secret.\nNote that any nodes that were using the secret will no longer be associated with the deleted secret.\n\nAuthorization Action:\n```\nsecrets:secrets:delete\n```", "operationId": "Delete", "responses": { "200": { @@ -73,6 +80,7 @@ "parameters": [ { "name": "id", + "description": "Unique node ID (UUID).", "in": "path", "required": true, "type": "string" @@ -83,6 +91,8 @@ ] }, "patch": { + "summary": "Update a secret", + "description": "Updates a secret. \nThis is a PATCH operation, meaning the details sent in will override/replace those stored in the DB.\nSecret information that is not in the body of the request will persist.\n\nExample:\n```\ngiven a credential with a username and password, a user could update the password by passing in the following body, \nand the name of the secret as well as the username for the secret be unchanged:\n\n{\n\"id\": \"525c013a-2ab3-4e6f-9005-51bc620e9157\",\n\"data\": [\n{ \"key\": \"password\", \"value\": \"new-value\"} \n]\n}\n```\n\nAuthorization Action:\n```\nsecrets:secrets:update\n```", "operationId": "Update", "responses": { "200": { @@ -95,6 +105,7 @@ "parameters": [ { "name": "id", + "description": "Unique node ID (UUID).", "in": "path", "required": true, "type": "string" @@ -115,6 +126,8 @@ }, "/secrets/search": { "post": { + "summary": "List and filter secrets", + "description": "Makes a list of secrets.\nSupports filtering, pagination, and sorting.\nAdding a filter narrows the list of secrets to only those that match the filter or filters.\nSupported filters: type\nSupported sort types: name, type, last modified\n\nExample:\n```\n{\n\"sort\": \"type\",\n\"order\": \"ASC\",\n\"filters\": [\n{ \"key\": \"type\", \"values\": [\"ssh\",\"winrm\",\"sudo\"] }\n],\n\"page\":1,\n\"per_page\":100\n}\n```\n\nAuthorization Action:\n```\nsecrets:secrets:list\n```", "operationId": "List", "responses": { "200": { @@ -182,7 +195,8 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique node ID (UUID)." } } }, @@ -193,21 +207,25 @@ "type": "array", "items": { "$ref": "#/definitions/chef.automate.api.common.query.Filter" - } + }, + "description": "Use filters to limit the set of secrets." }, "order": { "$ref": "#/definitions/chef.automate.api.secrets.Query.OrderType" }, "sort": { - "type": "string" + "type": "string", + "description": "Sort the results on a specific field." }, "page": { "type": "integer", - "format": "int32" + "format": "int32", + "description": "The number of result pages to return." }, "per_page": { "type": "integer", - "format": "int32" + "format": "int32", + "description": "The number of results on each page." } } }, @@ -217,35 +235,42 @@ "ASC", "DESC" ], - "default": "ASC" + "default": "ASC", + "description": "Return the results in ascending or descending order." }, "chef.automate.api.secrets.Secret": { "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique node ID (UUID)." }, "name": { - "type": "string" + "type": "string", + "description": "User-specified name for the secret." }, "type": { - "type": "string" + "type": "string", + "title": "Type of credential: ssh, winrm, sudo, aws, azure, gcp, service_now" }, "last_modified": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp denoting when the secret was last modified." }, "tags": { "type": "array", "items": { "$ref": "#/definitions/chef.automate.api.common.query.Kv" - } + }, + "description": "Tags to associate with the secret." }, "data": { "type": "array", "items": { "$ref": "#/definitions/chef.automate.api.common.query.Kv" - } + }, + "description": "Secret data, where the kv structs for the credential data live." } } }, @@ -256,11 +281,13 @@ "type": "array", "items": { "$ref": "#/definitions/chef.automate.api.secrets.Secret" - } + }, + "description": "List of secrets." }, "total": { "type": "integer", - "format": "int32" + "format": "int32", + "title": "Total count of secrets" } } }, diff --git a/components/automate-gateway/api/secrets.pb.swagger.go b/components/automate-gateway/api/secrets.pb.swagger.go index 6cea12af271..5eb55ad0af5 100644 --- a/components/automate-gateway/api/secrets.pb.swagger.go +++ b/components/automate-gateway/api/secrets.pb.swagger.go @@ -16,6 +16,8 @@ func init() { "paths": { "/secrets": { "post": { + "summary": "Create a secret", + "description": "Creates a secret. Requires values for name, type, and data.\n\nSupported types: ssh, winrm, sudo, aws, azure, gcp, service_now\nSupported keys by type: \nssh: username, password, key\nwinrm: username, password\nsudo: username, password\nservice_now: username, password\naws: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN\nazure: AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID\ngcp: GOOGLE_CREDENTIALS_JSON\n\nExample:\n` + "`" + `` + "`" + `` + "`" + `\n{\n\"name\": \"my ssh secret\",\n\"type\": \"ssh\",\n\"data\": [\n{ \"key\": \"username\", \"value\": \"vagrant\" },\n{ \"key\": \"password\", \"value\": \"vagrant\"} \n]\n}\n` + "`" + `` + "`" + `` + "`" + `\n\nAuthorization Action:\n` + "`" + `` + "`" + `` + "`" + `\nsecrets:secrets:create\n` + "`" + `` + "`" + `` + "`" + `", "operationId": "Create", "responses": { "200": { @@ -42,6 +44,8 @@ func init() { }, "/secrets/id/{id}": { "get": { + "summary": "Read a secret", + "description": "Reads a secret given the ID of the secret.\nNote that the secret information (password and key values) will not be returned by the API, as a safety measure.\n\nAuthorization Action:\n` + "`" + `` + "`" + `` + "`" + `\nsecrets:secrets:get\n` + "`" + `` + "`" + `` + "`" + `", "operationId": "Read", "responses": { "200": { @@ -54,6 +58,7 @@ func init() { "parameters": [ { "name": "id", + "description": "Unique node ID (UUID).", "in": "path", "required": true, "type": "string" @@ -64,6 +69,8 @@ func init() { ] }, "delete": { + "summary": "Delete a secret", + "description": "Deletes a secret given the ID of the secret.\nNote that any nodes that were using the secret will no longer be associated with the deleted secret.\n\nAuthorization Action:\n` + "`" + `` + "`" + `` + "`" + `\nsecrets:secrets:delete\n` + "`" + `` + "`" + `` + "`" + `", "operationId": "Delete", "responses": { "200": { @@ -76,6 +83,7 @@ func init() { "parameters": [ { "name": "id", + "description": "Unique node ID (UUID).", "in": "path", "required": true, "type": "string" @@ -86,6 +94,8 @@ func init() { ] }, "patch": { + "summary": "Update a secret", + "description": "Updates a secret. \nThis is a PATCH operation, meaning the details sent in will override/replace those stored in the DB.\nSecret information that is not in the body of the request will persist.\n\nExample:\n` + "`" + `` + "`" + `` + "`" + `\ngiven a credential with a username and password, a user could update the password by passing in the following body, \nand the name of the secret as well as the username for the secret be unchanged:\n\n{\n\"id\": \"525c013a-2ab3-4e6f-9005-51bc620e9157\",\n\"data\": [\n{ \"key\": \"password\", \"value\": \"new-value\"} \n]\n}\n` + "`" + `` + "`" + `` + "`" + `\n\nAuthorization Action:\n` + "`" + `` + "`" + `` + "`" + `\nsecrets:secrets:update\n` + "`" + `` + "`" + `` + "`" + `", "operationId": "Update", "responses": { "200": { @@ -98,6 +108,7 @@ func init() { "parameters": [ { "name": "id", + "description": "Unique node ID (UUID).", "in": "path", "required": true, "type": "string" @@ -118,6 +129,8 @@ func init() { }, "/secrets/search": { "post": { + "summary": "List and filter secrets", + "description": "Makes a list of secrets.\nSupports filtering, pagination, and sorting.\nAdding a filter narrows the list of secrets to only those that match the filter or filters.\nSupported filters: type\nSupported sort types: name, type, last modified\n\nExample:\n` + "`" + `` + "`" + `` + "`" + `\n{\n\"sort\": \"type\",\n\"order\": \"ASC\",\n\"filters\": [\n{ \"key\": \"type\", \"values\": [\"ssh\",\"winrm\",\"sudo\"] }\n],\n\"page\":1,\n\"per_page\":100\n}\n` + "`" + `` + "`" + `` + "`" + `\n\nAuthorization Action:\n` + "`" + `` + "`" + `` + "`" + `\nsecrets:secrets:list\n` + "`" + `` + "`" + `` + "`" + `", "operationId": "List", "responses": { "200": { @@ -185,7 +198,8 @@ func init() { "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique node ID (UUID)." } } }, @@ -196,21 +210,25 @@ func init() { "type": "array", "items": { "$ref": "#/definitions/chef.automate.api.common.query.Filter" - } + }, + "description": "Use filters to limit the set of secrets." }, "order": { "$ref": "#/definitions/chef.automate.api.secrets.Query.OrderType" }, "sort": { - "type": "string" + "type": "string", + "description": "Sort the results on a specific field." }, "page": { "type": "integer", - "format": "int32" + "format": "int32", + "description": "The number of result pages to return." }, "per_page": { "type": "integer", - "format": "int32" + "format": "int32", + "description": "The number of results on each page." } } }, @@ -220,35 +238,42 @@ func init() { "ASC", "DESC" ], - "default": "ASC" + "default": "ASC", + "description": "Return the results in ascending or descending order." }, "chef.automate.api.secrets.Secret": { "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique node ID (UUID)." }, "name": { - "type": "string" + "type": "string", + "description": "User-specified name for the secret." }, "type": { - "type": "string" + "type": "string", + "title": "Type of credential: ssh, winrm, sudo, aws, azure, gcp, service_now" }, "last_modified": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp denoting when the secret was last modified." }, "tags": { "type": "array", "items": { "$ref": "#/definitions/chef.automate.api.common.query.Kv" - } + }, + "description": "Tags to associate with the secret." }, "data": { "type": "array", "items": { "$ref": "#/definitions/chef.automate.api.common.query.Kv" - } + }, + "description": "Secret data, where the kv structs for the credential data live." } } }, @@ -259,11 +284,13 @@ func init() { "type": "array", "items": { "$ref": "#/definitions/chef.automate.api.secrets.Secret" - } + }, + "description": "List of secrets." }, "total": { "type": "integer", - "format": "int32" + "format": "int32", + "title": "Total count of secrets" } } },