warewulf/internal/pkg/api/routes/v1/routes.proto

// Routes for the wwapi (WareWulf API).
// TODO: Try protoc-gen-doc for generating documentation.

syntax = "proto3";

option go_package = "internal/pkg/api/routes/wwapiv1;wwapiv1";

package wwapi.v1;

import "google/protobuf/empty.proto";
import "google/api/annotations.proto";

// Information about the database

message NodeDBHash {
	string hash = 1;
}

// Image

// ImageBuildParameter contains input for building zero or more images.
message ImageBuildParameter {
	repeated string imageNames = 1;
	bool force = 2;
	bool all = 3;
	// bool default = 4;
}

// ImageDeleteParameter contains input for removing images from Warewulf
// management.
message ImageDeleteParameter {
	repeated string imageNames = 1;
}

// ImageCopyParameter contains 2 inputs : first one for the image source name and second one for the duplicated image name.
message ImageCopyParameter {
	string imageSource = 1;
	string imageDestination = 2;
	bool build = 3;
}

// ImageImportParameter has all input for importing an image.
message ImageImportParameter{
	string source = 1; // image source uri
	string name = 2; // image name
	bool force = 3;
	bool update = 4;
	bool build = 5;
	// bool default = 6;
	bool syncUser = 7;
	bool ociNoHttps = 8;
	string ociUsername = 9;
	string ociPassword = 10;
	string platform = 11;
}

// ImageInfo has data on each image. This is emitted in the
// ImageListResponse.
message ImageInfo {
	string name = 1;
	uint32 nodeCount = 2;
	string kernelVersion = 3;
	uint64 createDate = 4; // creation date in unix time
	uint64 modDate = 5; // date of last modification in unix time
	// uint64 size = 6; // size of chroot and images in bytes
	uint64 imgSize = 7;
	uint64 imgSizeComp = 8;
}

// ImageListResponse has all information that ImageList provides.
message ImageListResponse {
	repeated ImageInfo images = 1;
}

// ImageShowParameter is the input for ImageShow.
message ImageShowParameter {
	string imageName = 1;
}

// ImageShowResponse has all information emitted on ImageShow.
message ImageShowResponse {
	string Name = 1;
	string Rootfs = 2;
	repeated string Nodes = 3;
	string KernelVersion = 4;
}

// ImageSyncUserParameter is the input for ImageSyncUser.
message ImageSyncUserParameter {
	string imageName = 1;
}

// ImageRenameParameter is the input for ImageRename
message ImageRenameParameter {
	string imageName = 1;
	string targetName = 2;
	bool build = 3;
}

// Nodes

// NodeNames is an array of node ids.
message NodeNames {
	repeated string nodeNames = 1;
}

// NodeField contains data output on NodeList.
message NodeField {
	string source = 1;
	string value = 2; // TODO: Variable name okay?
	string print = 3; // Empty values printed as -- in wwctl.
}

// NetDev is network devices (NICs) on a node.
message NetDev {
	map<string, NodeField> Field = 1;
	map<string, NodeField> Tags = 9;
}

// NodeInfo contains details about a node managed by Warewulf/
message NodeInfo {
	map<string, NodeField> Fields = 1;
	map<string, NetDev> NetDevs = 23;
	map<string, NodeField> Tags = 24;
	map<string, NodeField> Keys = 25; // TODO: We may not need this. Tags may be it. Ask Greg.
}

// NodeListResponse is the output of NodeList.
message NodeListResponse {
	repeated NodeInfo nodes = 1;
}

// Request a node list
message GetNodeList {
	enum ListType {
		Simple = 0;
		Ipmi = 1;
		Network = 2;
		Long = 3;
		All = 4;
		YAML = 6;
		JSON = 7;
	}
	ListType type = 8;
	repeated string Nodes = 9;
}

// Get the formated output as string
message NodeList {
	repeated string Output = 1;
}

// Request a profile list view
message GetProfileList {
	bool ShowAll = 1;
	bool ShowYaml = 3;
	bool ShowJson = 4;
	repeated string Profiles = 5;
}
// Get the formated output as string
message ProfileList {
	repeated string Output = 1;
}

// NodeAddParameter contains all input for adding a node to be managed by
// Warewulf. Only adds nodes if the hash matches the actual hash of the
// configuration.
message NodeAddParameter {
	string nodeConfYaml = 1;
	bool force = 2;
	string hash = 3;
	repeated string nodeNames = 10;
}

// NodeYaml is just the updated YAML config which will be added
// to nodes.conf (is resused for profile edit)
message NodeYaml {
	string nodeConfMapYaml = 1;
	string hash = 2;
}

// NodeDeleteParameter contains input for removing nodes from Warewulf
// management. If the given hash differs with the actual hash of the
// configuration, no node is deleted. The force option allows the deletion
// of nodes with a correct hash.
message NodeDeleteParameter {
	bool force = 1;
	repeated string nodeNames = 2;
	string hash = 3;
}

// NodeSetParameter contains all fields for updating aspects of nodes managed
// by Warewulf.
message ConfSetParameter {
	string nodeConfYaml = 1;
    string netdevDelete = 2;
	string diskDelete = 3;
	string partitionDelete = 4;
	string filesystemDelete = 5;
	bool allConfs = 6;
	bool force = 7;
	repeated string confList = 8;
	map<string, string> tagAdd = 9;
	map<string, string> netTagAdd = 10;
	map<string, string> ipmiTagAdd = 11;
	repeated string tagDel = 12;
	repeated string netTagDel = 13;
	repeated string ipmiTagDel = 14;
	string netdev = 15;

}

// NodeStatus contains information about the imaging status per node.
message NodeStatus {
	string nodeName = 1;	// Name (Id) of the node.
	string stage = 2;		// Stage of imaging.
	string sent = 3;		// Last overlay sent.
	string ipaddr = 4;		// Node IP address.
	int64 lastseen = 5;		// Time in seconds since the node was last seen.
}

// NodeStatusResponse contains NodeStatus for zero or more nodes.
message NodeStatusResponse {
	repeated NodeStatus nodeStatus = 1;
}

// Version

// VersionReponse contains versions of the software.
message VersionResponse {
	string apiPrefix = 1;
	string apiVersion = 2;
	string warewulfVersion = 3;
}

// Check if config is writeable
message CanWriteConfig {
	bool canWriteConfig = 1;
}

// WWApi defines the wwapid service web interface.
service WWApi {

	// Images

	// ImageBuild builds zero or more images.
	rpc ImageBuild(ImageBuildParameter) returns (ImageListResponse) {
		option (google.api.http) = {
			post: "/v1/imagebuild"
			body: "*"
		};
	}

	// ImageDelete removes one or more image from Warewulf management.
	rpc ImageDelete(ImageDeleteParameter) returns (google.protobuf.Empty) {
		option (google.api.http) = {
			delete: "/v1/image"
		};
	}


	rpc ImageCopy(ImageCopyParameter) returns (google.protobuf.Empty) {
		option (google.api.http) = {
			post: "/v1/imagecopy"
			body: "*"
		};
	}
	// ImageImport imports an image to Warewulf.
	rpc ImageImport(ImageImportParameter) returns (ImageListResponse) {
		option(google.api.http) = {
			post: "/v1/image"
			body: "*"
		};
	}

	// ImageList lists ImageInfo for each image.
	rpc ImageList(google.protobuf.Empty) returns (ImageListResponse) {
		option (google.api.http) = {
			get: "/v1/image"
		};
	}

	// ImageShow lists ImageShow for each image.
	rpc ImageShow(ImageShowParameter) returns (ImageShowResponse) {
		option (google.api.http) = {
			get: "/v1/imageshow"
		};
	}

	// ImageRename renames the image
	rpc ImageRename(ImageRenameParameter) returns (google.protobuf.Empty) {
		option (google.api.http) = {
			post: "/v1/imagerename"
			body: "*"
		};
	}

	// Nodes

	// NodeAdd adds one or more nodes for management by Warewulf and returns
	// the added nodes. Node fields may be shimmed in per profiles.
	rpc NodeAdd(NodeAddParameter) returns (NodeListResponse) {
		option (google.api.http) = {
			post: "/v1/node"
			body: "*"
		};
	}

	// NodeDelete removes one or more nodes from Warewulf management.
	rpc NodeDelete(NodeDeleteParameter) returns (google.protobuf.Empty) {
		option (google.api.http) = {
			delete: "/v1/node"
		};
	}

	// NodeList lists some or all nodes managed by Warewulf.
	rpc NodeList(NodeNames) returns (NodeListResponse) {
		option (google.api.http) = {
			get: "/v1/node"
		};
	}

	// NodeSet updates node fields for one or more nodes.
	rpc NodeSet(ConfSetParameter) returns (NodeListResponse) {
		option (google.api.http) = {
			post: "/v1/nodeset" // TODO: This should be a patch. Had trouble getting patch to work at all.
			body: "*"
		};
	}

	// NodeStatus returns the imaging state for nodes.
	// This requires warewulfd.
	rpc NodeStatus(NodeNames) returns (NodeStatusResponse) {
		option (google.api.http) = {
			get: "/v1/nodestatus"
		};
	}

	// Version returns the wwapi version, the api prefix, and the Warewulf
	// version. This is also useful for testing if the service is up.
	rpc Version(google.protobuf.Empty) returns (VersionResponse) {
        option (google.api.http) = {
            get: "/version"
        };
    }
}