src/kudu/tools/tool.proto

// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.
syntax = "proto2";
package kudu.tools;

option java_package = "org.apache.kudu.tools";

import "kudu/common/common.proto";
import "kudu/common/wire_protocol.proto";
import "kudu/tablet/metadata.proto";
import "kudu/tablet/tablet.proto";

// Creates a new ExternalMiniCluster.
//
// The below fields generally map to options from ExternalMiniClusterOptions.
// If not provided, the defaults from that class will be used instead.
//
// Only one cluster may be created at a time.
message CreateClusterRequestPB {
  // The desired number of masters.
  //
  // Currently only one or three masters are supported.
  optional int32 num_masters = 1;

  // The desired number of tablet servers.
  optional int32 num_tservers = 2;

  // Whether or not the cluster should be Kerberized.
  optional bool enable_kerberos = 3;

  // Service principal name used by the cluster if Kerberos is enabled (default:
  // "kudu").
  optional string principal = 10;

  // Whether or not Ranger should be enabled
  optional bool enable_ranger = 9;

  // Whether or not to create a Hive Metastore, and/or enable Kudu Hive
  // Metastore integration.
  optional HmsMode hms_mode = 7;

  // The directory where the cluster's data and logs should be placed.
  optional string cluster_root = 4;

  // Any additional gflags for masters or tablet servers. Each should be in a
  // a format that's expected by gflag (i.e. "--foo=bar").
  repeated string extra_master_flags = 5;
  repeated string extra_tserver_flags = 6;

  message MiniKdcOptionsPB {
    // The default lifetime for initial ticket requests.
    optional string ticket_lifetime = 1;
    // The default renewable lifetime for initial ticket requests.
    optional string renew_lifetime = 2;
  }
  optional MiniKdcOptionsPB mini_kdc_options = 8;
}

// Destroys a cluster created via 'create_cluster'.
message DestroyClusterRequestPB {}

// Starts all daemons in a newly created cluster, or restart all daemons
// in a stopped cluster.
//
// No-op for already started clusters.
message StartClusterRequestPB {}

// Stops a cluster.
//
// No-op for already stopped clusters.
message StopClusterRequestPB {}

// Type of daemon managed in a cluster.
enum DaemonType {
  UNKNOWN_DAEMON = 0;
  MASTER = 1;
  TSERVER = 2;
  KDC = 3;
}

// Identifier for a cluster daemon, unique to the cluster.
message DaemonIdentifierPB {
  // Whether the daemon is a master, tserver, or whatever.
  optional DaemonType type = 1;

  // Index of the daemon in the cluster, if the cluster has multiple daemons
  // of this type.
  optional uint32 index = 2;
}

// Restart a stopped daemon.
message StartDaemonRequestPB {
  // The identifier of the daemon to be restarted. This identifier is unique
  // and immutable for the lifetime of the cluster.
  optional DaemonIdentifierPB id = 1;
}

// Stops a started daemon.
//
// No-op for already stopped daemons.
message StopDaemonRequestPB {
  // The identifier of the daemon to be stopped. This identifier is unique
  // and immutable for the lifetime of the cluster.
  optional DaemonIdentifierPB id = 1;
}

// Pause a daemon: send SIGSTOP signal to the process.
message PauseDaemonRequestPB {
  // The identifier of the daemon to be paused.
  optional DaemonIdentifierPB id = 1;
}

// Resume a paused daemon: send SIGCONT signal to the process.
message ResumeDaemonRequestPB {
  // The identifier of the daemon to be resumed.
  optional DaemonIdentifierPB id = 1;
}

// Daemon information.
message DaemonInfoPB {
  // Unique identifier of the daemon.
  optional DaemonIdentifierPB id = 1;

  // Daemon's bound RPC address.
  optional HostPortPB bound_rpc_address = 2;
}

// Response to a GetMastersRequestPB.
message GetMastersResponsePB {
  // List of masters.
  repeated DaemonInfoPB masters = 1;
}

// Gets information on each started master.
message GetMastersRequestPB {}

// Response to a GetTServersRequestPB.
message GetTServersResponsePB {
  // List of tablet servers.
  repeated DaemonInfoPB tservers = 1;
}

// Gets information on each started tablet server.
message GetTServersRequestPB {}

// Response to a GetKDCEnvVarsRequestPB.
message GetKDCEnvVarsResponsePB {

  // Environment variables, mapped from key to value.
  map<string, string> env_vars = 1;
}

// Gets all environment variables another process may need in order to
// communicate with this cluster's KDC.
//
// It is an error to call this on a non-Kerberized cluster.
message GetKDCEnvVarsRequestPB {}

// Removes all credentials for all principals from the KDC credential cache.
message KdestroyRequestPB {};

// Establishes a new Kerberos ticket cache (equivalent to running 'kinit').
message KinitRequestPB {
  optional string username = 1 [ default = "test-admin" ];
};

// Call SetFlag() on the specific daemon.
message SetDaemonFlagRequestPB {
  // The identifier of the daemon to sent the request to.
  optional DaemonIdentifierPB id = 1;
  // The name of the flag to set.
  optional string flag = 2;
  // Value to set.
  optional string value = 3;
}

// Sent by the control shell in response to a control shell command request.
message ControlShellResponsePB {

  // Only set if there was some kind of shell-side error.
  optional AppStatusPB error = 1;

  // The command response. Only set for commands that actually expect a response.
  oneof response {
    GetMastersResponsePB get_masters = 2;
    GetTServersResponsePB get_tservers = 3;
    GetKDCEnvVarsResponsePB get_kdc_env_vars = 4;
  }
}

// Command sent to the control shell.
//
// Because the control shell communicates via pipe and not krpc, we can't make
// use of service dispatch and must instead multiplex all command requests and
// responses via ControlShellRequestPB and ControlShellResponsePB respectively.
message ControlShellRequestPB {

  // The command request.
  oneof request {
    CreateClusterRequestPB create_cluster = 1;
    DestroyClusterRequestPB destroy_cluster = 2;
    StartClusterRequestPB start_cluster = 3;
    StopClusterRequestPB stop_cluster = 4;
    StartDaemonRequestPB start_daemon = 5;
    StopDaemonRequestPB stop_daemon = 6;
    GetMastersRequestPB get_masters = 7;
    GetTServersRequestPB get_tservers = 8;
    GetKDCEnvVarsRequestPB get_kdc_env_vars = 9;
    KdestroyRequestPB kdestroy = 10;
    KinitRequestPB kinit = 11;
    SetDaemonFlagRequestPB set_daemon_flag = 12;
    PauseDaemonRequestPB pause_daemon = 13;
    ResumeDaemonRequestPB resume_daemon = 14;
  }
}

// Results of ksck, the Kudu system check.
// See the struct analogues of these messages in ksck_results.h.
message KsckResultsPB {
  repeated string errors = 1;

  repeated ServerHealthSummaryPB master_summaries = 2;
  repeated ServerHealthSummaryPB tserver_summaries = 3;

  repeated string master_uuids = 4;
  optional bool master_consensus_conflict = 5;
  repeated ConsensusStatePB master_consensus_states = 6;

  repeated TabletSummaryPB tablet_summaries = 7;
  repeated TableSummaryPB table_summaries = 8;
  repeated TableSummaryPB system_table_summaries = 12;

  optional KsckChecksumResultsPB checksum_results = 9;
  repeated KsckVersionSummaryPB version_summaries = 10;
  repeated KsckCountSummaryPB count_summaries = 11;
}

message ServerHealthSummaryPB {
  enum ServerHealth {
    UNKNOWN = 999;
    HEALTHY = 0;
    UNAVAILABLE = 1;
    WRONG_SERVER_UUID = 2;
    UNAUTHORIZED = 3;
  }
  optional string uuid = 1;
  optional string address = 2;
  optional ServerHealth health = 3;
  optional string status = 4;
  optional string version = 5;
  optional string location = 6;
}

message ConsensusStatePB {
  enum ConfigType {
    UNKNOWN = 999;
    MASTER = 0;
    COMMITTED = 1;
    PENDING = 2;
  }
  optional ConfigType type = 1;
  optional int64 term = 2;
  optional int64 opid_index = 3;
  optional string leader_uuid = 4;
  repeated string voter_uuids = 5;
  repeated string non_voter_uuids = 6;
}

enum KsckTabletHealthPB {
  UNKNOWN = 999;
  HEALTHY = 0;
  RECOVERING = 1;
  UNDER_REPLICATED = 2;
  UNAVAILABLE = 3;
  CONSENSUS_MISMATCH = 4;
}

message TabletSummaryPB {
  optional string id = 1;
  optional string table_id = 2;
  optional string table_name = 3;
  optional KsckTabletHealthPB health = 4;
  optional string status = 5;
  optional ConsensusStatePB master_cstate = 6;
  repeated ReplicaSummaryPB replicas = 7;
  optional string range_key_begin = 8;
}

message ReplicaSummaryPB {
  optional string ts_uuid = 1;
  optional string ts_address = 2;
  optional bool ts_healthy = 3;
  optional bool is_leader = 4;
  optional bool is_voter = 5;
  optional tablet.TabletStatePB state = 6;
  optional tablet.TabletStatusPB status_pb = 7;
  optional ConsensusStatePB consensus_state = 8;
}

message TableSummaryPB {
  optional string id = 1;
  optional string name = 2;
  optional KsckTabletHealthPB health = 3;
  optional int32 replication_factor = 4;
  optional int32 total_tablets = 5;
  optional int32 healthy_tablets = 6;
  optional int32 recovering_tablets = 7;
  optional int32 underreplicated_tablets = 8;
  optional int32 unavailable_tablets = 9;
  optional int32 consensus_mismatch_tablets = 10;
}

message KsckChecksumResultsPB {
  optional fixed64 snapshot_timestamp = 1;
  repeated KsckTableChecksumPB tables = 2;
}

message KsckTableChecksumPB {
  optional string name = 1;
  repeated KsckTabletChecksumPB tablets = 2;
}

message KsckTabletChecksumPB {
  optional string tablet_id = 1;
  optional bool mismatch = 2;
  repeated KsckReplicaChecksumPB replica_checksums = 3;
}

message KsckReplicaChecksumPB {
  optional string ts_address = 1;
  optional string ts_uuid = 2;
  optional string status = 3;
  optional fixed64 checksum = 4;
}

message KsckVersionSummaryPB {
  optional string version = 1;
  repeated string servers = 2;
}

message KsckCountSummaryPB {
  optional int32 masters = 1;
  optional int32 tservers = 2;
  optional int32 tables = 3;
  optional int32 tablets = 4;
  optional int32 replicas = 5;
}

message ColumnPB {
  enum EncodingType {
    AUTO_ENCODING = 0;
    PLAIN_ENCODING = 1;
    PREFIX_ENCODING = 2;
    RLE = 3;
    DICT_ENCODING = 4;
    BIT_SHUFFLE = 5;
  }
  enum CompressionType {
    DEFAULT_COMPRESSION = 0;
    NO_COMPRESSION = 1;
    SNAPPY = 2;
    LZ4 = 3;
    ZLIB = 4;
  }
  message ColumnAttributesPB {
    // For decimal columns.
    optional int32 precision = 1;
    optional int32 scale = 2;
    // For varchar columns.
    optional int32 length = 3;
  }
  optional string column_name = 1;
  optional string column_type = 2;
  optional bool is_nullable = 3;
  // The default value takes the form of a literal string.
  optional string default_value = 4;
  optional string comment = 5;
  optional EncodingType encoding = 6;
  optional CompressionType compression = 7;
  // Column's attribute, used for DECIMAL and VARCHAR type columns.
  optional ColumnAttributesPB type_attributes = 8;
  // The preferred block size for cfile blocks.
  optional int32 cfile_block_size = 9;
}

message PartitionPB {
  message HashPartitionPB {
    // Column names of columns included in the hash. Every column must be
    // a component of the primary key.
    repeated string columns = 1;
    // Number of buckets into which columns will be hashed. Must be at least 2.
    optional int32 num_buckets = 2;
    // Seed value for hash calculation. Administrators may set a seed value
    // on a per-table basis in order to randomize the mapping of rows to
    // buckets. Setting a seed provides some amount of protection against denial
    // of service attacks when the hash bucket columns contain user provided
    // input.
    optional uint32 seed = 3;
  }

  message RangePartitionPB {
    message BoundPB {
      enum Type {
        UNKNOWN_BOUND = 0;
        EXCLUSIVE = 1;
        INCLUSIVE = 2;
      }
      // The type of range partition bound, "INCLUSIVE" or "EXCLUSIVE"
      optional Type bound_type = 1;
      // The start or end partition key values. Bounds value should be simply the
      // exact string value for the bound.
      repeated string bound_values = 2;
    }
    message RangeBoundPB {
      // The lower bound.
      optional BoundPB lower_bound = 1;
      // The upper bound.
      optional BoundPB upper_bound = 2;
    }
    message SplitValuePB {
      // The split values of range partition keys. Split value should be simply the
      // exact string value for the bound.
      repeated string split_values = 1;
    }
    message RangeWithHashSchemaPB {
      // The bounds of this range.
      optional RangeBoundPB range_bounds = 1;
      // Hash schema for this range.
      repeated HashPartitionPB hash_schema = 2;
    }

    // Column names of columns included in the range. All columns must be
    // a component of the primary key.
    repeated string columns = 1;
    // Range bounds.
    repeated RangeBoundPB range_bounds = 2;
    // Range splits.
    repeated SplitValuePB range_splits = 3;
    // Ranges with custom hash schemas.
    repeated RangeWithHashSchemaPB custom_hash_schema_ranges = 4;
  }

  // A standalone message representing a hash schema.
  message HashSchemaPB {
    repeated HashPartitionPB hash_schema = 1;
  }

  // Table-wide hash schema.
  repeated HashPartitionPB hash_partitions = 1;
  // Range partitioning information.
  optional RangePartitionPB range_partition = 2;
}

message ExtraConfigPB {
  map<string, string> configs = 1;
}

message SchemaPB {
  // Representation of table's columns, include more than one column message.
  repeated ColumnPB columns = 1;
  // The table's primary keys.
  repeated string key_column_names = 2;
}

// Create table protobuffer message. The JSON message provided by user
// is converted to the PB. Used for creating a new table by kudu tool.
message CreateTablePB {
  optional string table_name = 1;
  // Representation of a table's schema.
  optional SchemaPB schema = 2;
  // Information on the table partitioning.
  optional PartitionPB partition = 3;
  // Number of replicas for table's tablets.
  optional int32 num_replicas = 4;
  // The table's extra configuration properties.
  optional ExtraConfigPB extra_configs = 5;
  // The dimension label for tablets that were created during table creation.
  // Used for dimension-specific placement of tablet replicas corresponding
  // to the partitions of the newly created table.
  optional string dimension_label = 6;
  // The owner for the newly created table. If not specified, the owner is
  // automatically set to the effective OS user name that the kudu CLI tool is
  // run with.
  optional string owner = 7;
  // Table's comment.
  optional string comment = 8;
}

message TablesInfoPB {
  message ReplicaInfoPB {
    optional string role = 1;
    optional string uuid = 2;
    optional string host_port = 3;
  }

  message TabletWithPartitionPB {
    optional string tablet_id = 1;
    optional string partition_info = 2;
    repeated ReplicaInfoPB replica_info = 3;
  }

  message TableInfoPB {
    optional string name = 1;
    optional int32 num_tablets = 2;
    optional int32 num_replicas = 3;
    optional uint64 live_row_count = 4;
    repeated TabletWithPartitionPB tablet_with_partition = 5;
  }

  repeated TableInfoPB tables = 1;
}