service.proto

// Copyright (c) 2017 Cisco and/or its affiliates.
//
// Licensed 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 = "proto3";

// Package service defines data model for Kubernetes Service.
package service;

// Service is a named abstraction of software service (for example, mysql)
// consisting of local port (for example 3306) that the proxy listens on,
// and the selector that determines which pods will answer requests sent
// through the proxy.
message Service {
    // Name of the service unique within the namespace.
    // Cannot be updated.
    string name = 1;

    // Namespace the service is inserted into.
    // An empty namespace is equivalent to the "default" namespace, but "default"
    // is the canonical representation used in the key for a key-value store.
    // Cannot be updated.
    string namespace = 2;

    // ServicePort contains information on service's port.
    message ServicePort {
        // The name of this port within the service. This must be a DNS_LABEL.
        // All ports within a ServiceSpec must have unique names. This maps to
        // the 'Name' field in EndpointPort objects.
        // Optional if only one ServicePort is defined on this service.
        // +optional
        string name = 1;

        // The IP protocol for this port. Supports "TCP" and "UDP".
        // Default is TCP.
        // +optional
        string protocol = 2;

        // The port that will be exposed by this service.
        int32 port = 3;

        // Number or name of the port to access on the pods targeted by the service.
        // Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME.
        // If this is a string, it will be looked up as a named port in the
        // target Pod's container ports. If this is not specified, the value
        // of the 'port' field is used (an identity map).
        // This field is ignored for services with clusterIP=None, and should be
        // omitted or set equal to the 'port' field.
        // +optional
        message IntOrString {
            enum Type {
                NUMBER = 0;
                STRING = 1;

            }
            Type type = 1;
            int32 int_val = 2;
            string string_val = 3;
        }
        IntOrString target_port = 4;

        // The port on each node on which this service is exposed when
        // type=NodePort or LoadBalancer.
        int32 node_port = 5;
    }
    // The list of ports that are exposed by this service.
    repeated ServicePort port = 3;

    // Route service traffic to pods with label keys and values matching this
    // selector. If empty or not present, the service is assumed to have an
    // external process managing its endpoints, which Kubernetes will not
    // modify. Only applies to types ClusterIP, NodePort, and LoadBalancer.
    // Ignored if type is ExternalName.
    // More info: https://kubernetes.io/docs/concepts/services-networking/service/
    // +optional
    map<string,string> selector = 4;

    // ClusterIP is the IP address of the service and is usually assigned
    // randomly by the master. If an address is specified manually and is not in
    // use by others, it will be allocated to the service; otherwise, creation
    // of the service will fail. This field can not be changed through updates.
    // Valid values are "None", empty string (""), or a valid IP address. "None"
    // can be specified for headless services when proxying is not required.
    // Only applies to types ClusterIP, NodePort, and LoadBalancer. Ignored if
    // type is ExternalName.
    // More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies
    // +optional
    string cluster_ip = 5;

    // ServiceType determines how the Service is exposed. Defaults to ClusterIP. Valid
    // options are ExternalName, ClusterIP, NodePort, and LoadBalancer.
    // "ExternalName" maps to the specified externalName.
    // "ClusterIP" allocates a cluster-internal IP address for load-balancing
    // to endpoints. Endpoints are determined by the selector or if that is
    // not specified, by manual construction of an Endpoints object. If
    // clusterIP is "None", no virtual IP is allocated and the endpoints are
    // published as a set of endpoints rather than a stable IP.
    // "NodePort" builds on ClusterIP and allocates a port on every node which
    // routes to the clusterIP.
    // "LoadBalancer" builds on NodePort and creates an
    // external load-balancer (if supported in the current cloud) which routes
    // to the clusterIP.
    // More info: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services---service-types
    // +optional
    string service_type = 6;

    // ExternalIPs is a list of IP addresses for which nodes in the cluster
    // will also accept traffic for this service.  These IPs are not managed
    // by Kubernetes.  The user is responsible for ensuring that traffic
    // arrives at a node with this IP.  A common example is external
    // load-balancers that are not part of the Kubernetes system.
    // +optional
    repeated string external_ips = 7;

    // A list of IP addresses set as ingress points for IP-based load-balancers
    // (typically GCE, MetalLB or OpenStack load-balancers).
    // Only applies to Service Type: LoadBalancer
    // +optional
    repeated string lb_ingress_ips = 8;

    // Supports "ClientIP" and "None". Used to maintain session affinity.
    // Enable client IP based session affinity.
    // Must be ClientIP or None.
    // Defaults to None.
    // More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies
    // +optional
    string session_affinity = 9;

    // Only applies to Service Type: LoadBalancer
    // LoadBalancer will get created with the IP specified in this field.
    // This feature depends on whether the underlying cloud-provider supports
    // specifying the loadBalancerIP when a load balancer is created.
    // This field will be ignored if the cloud-provider does not support the
    // feature.
    // +optional
    string loadbalancer_ip = 10;

    // If specified and supported by the platform, this will restrict traffic
    // through the cloud-provider load-balancer will be restricted to the
    // specified client IPs. This field will be ignored if the cloud-provider
    // does not support the feature."
    // More info: https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/
    // +optional
    repeated string loadbalancer_source_ranges = 11;

    // externalTrafficPolicy denotes if this Service desires to route external
    // traffic to node-local or cluster-wide endpoints. "Local" preserves the
    // client source IP and avoids a second hop for LoadBalancer and Nodeport
    // type services, but risks potentially imbalanced traffic spreading.
    // "Cluster" obscures the client source IP and may cause a second hop to
    // another node, but should have good overall load-spreading.
    // +optional
    string external_traffic_policy = 12;

    // healthCheckNodePort specifies the healthcheck nodePort for the service.
    // If not specified, HealthCheckNodePort is created by the service api
    // backend with the allocated nodePort. Will use user-specified nodePort
    // value if specified by the client. Only effects when Type is set to
    // LoadBalancer and ExternalTrafficPolicy is set to Local.
    // +optional
    int32 health_check_node_port = 13;

    // timeoutSeconds specifies the seconds of ClientIP type session sticky time.
    // The value must be >0 && <=86400(for 1 day).
    // Default value is 10800(for 3 hours). 0 - means that affinity is disabled.
    uint32 session_affinity_timeout = 14;

    // annotations is an unstructured key value map stored with a resource that may be
    // set by external tools to store and retrieve arbitrary metadata. They are not
    // queryable and should be preserved when modifying objects.
    // More info: http://kubernetes.io/docs/user-guide/annotations
    // +optional
    map<string,string> annotations = 15;
}