github_com_openshift_origin_pkg_route_apis_route_v1.proto

// This file was autogenerated by go-to-protobuf. Do not edit it manually!

syntax = 'proto2';

package github.com.openshift.origin.pkg.route.apis.route.v1;

import "k8s.io/apimachinery/pkg/apis/meta/v1/generated.proto";
import "k8s.io/apimachinery/pkg/runtime/generated.proto";
import "k8s.io/apimachinery/pkg/runtime/schema/generated.proto";
import "k8s.io/apimachinery/pkg/util/intstr/generated.proto";
import "k8s.io/kubernetes/pkg/api/v1/generated.proto";

// Package-wide variables from generator "generated".
option go_package = "v1";

// A route allows developers to expose services through an HTTP(S) aware load balancing and proxy
// layer via a public DNS entry. The route may further specify TLS options and a certificate, or
// specify a public CNAME that the router should also accept for HTTP and HTTPS traffic. An
// administrator typically configures their router to be visible outside the cluster firewall, and
// may also add additional security, caching, or traffic controls on the service content. Routers
// usually talk directly to the service endpoints.
// 
// Once a route is created, the `host` field may not be changed. Generally, routers use the oldest
// route with a given host when resolving conflicts.
// 
// Routers are subject to additional customization and may support additional controls via the
// annotations field.
// 
// Because administrators may configure multiple routers, the route status field is used to
// return information to clients about the names and states of the route under each router.
// If a client chooses a duplicate name, for instance, the route status conditions are used
// to indicate the route cannot be chosen.
message Route {
  // Standard object metadata.
  optional k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta metadata = 1;

  // spec is the desired state of the route
  optional RouteSpec spec = 2;

  // status is the current state of the route
  optional RouteStatus status = 3;
}

// RouteIngress holds information about the places where a route is exposed.
message RouteIngress {
  // Host is the host string under which the route is exposed; this value is required
  optional string host = 1;

  // Name is a name chosen by the router to identify itself; this value is required
  optional string routerName = 2;

  // Conditions is the state of the route, may be empty.
  repeated RouteIngressCondition conditions = 3;

  // Wildcard policy is the wildcard policy that was allowed where this route is exposed.
  optional string wildcardPolicy = 4;

  // CanonicalHostname is the external host name for the router that can be used as a CNAME
  // for the host requested for this route. This value is optional and may not be set in all cases.
  optional string routerCanonicalHostname = 5;
}

// RouteIngressCondition contains details for the current condition of this route on a particular
// router.
message RouteIngressCondition {
  // Type is the type of the condition.
  // Currently only Ready.
  optional string type = 1;

  // Status is the status of the condition.
  // Can be True, False, Unknown.
  optional string status = 2;

  // (brief) reason for the condition's last transition, and is usually a machine and human
  // readable constant
  optional string reason = 3;

  // Human readable message indicating details about last transition.
  optional string message = 4;

  // RFC 3339 date and time when this condition last transitioned
  optional k8s.io.apimachinery.pkg.apis.meta.v1.Time lastTransitionTime = 5;
}

// RouteList is a collection of Routes.
message RouteList {
  // Standard object metadata.
  optional k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta metadata = 1;

  // items is a list of routes
  repeated Route items = 2;
}

// RoutePort defines a port mapping from a router to an endpoint in the service endpoints.
message RoutePort {
  // The target port on pods selected by the service this route points to.
  // If this is a string, it will be looked up as a named port in the target
  // endpoints port list. Required
  optional k8s.io.apimachinery.pkg.util.intstr.IntOrString targetPort = 1;
}

// RouteSpec describes the hostname or path the route exposes, any security information,
// and one to four backends (services) the route points to. Requests are distributed
// among the backends depending on the weights assigned to each backend. When using
// roundrobin scheduling the portion of requests that go to each backend is the backend
// weight divided by the sum of all of the backend weights. When the backend has more than
// one endpoint the requests that end up on the backend are roundrobin distributed among
// the endpoints. Weights are between 0 and 256 with default 1. Weight 0 causes no requests
// to the backend. If all weights are zero the route will be considered to have no backends
// and return a standard 503 response.
// 
// The `tls` field is optional and allows specific certificates or behavior for the
// route. Routers typically configure a default certificate on a wildcard domain to
// terminate routes without explicit certificates, but custom hostnames usually must
// choose passthrough (send traffic directly to the backend via the TLS Server-Name-
// Indication field) or provide a certificate.
message RouteSpec {
  // host is an alias/DNS that points to the service. Optional.
  // If not specified a route name will typically be automatically
  // chosen.
  // Must follow DNS952 subdomain conventions.
  optional string host = 1;

  // Path that the router watches for, to route traffic for to the service. Optional
  optional string path = 2;

  // to is an object the route should use as the primary backend. Only the Service kind
  // is allowed, and it will be defaulted to Service. If the weight field (0-256 default 1)
  // is set to zero, no traffic will be sent to this backend.
  optional RouteTargetReference to = 3;

  // alternateBackends allows up to 3 additional backends to be assigned to the route.
  // Only the Service kind is allowed, and it will be defaulted to Service.
  // Use the weight field in RouteTargetReference object to specify relative preference.
  repeated RouteTargetReference alternateBackends = 4;

  // If specified, the port to be used by the router. Most routers will use all
  // endpoints exposed by the service by default - set this value to instruct routers
  // which port to use.
  optional RoutePort port = 5;

  // The tls field provides the ability to configure certificates and termination for the route.
  optional TLSConfig tls = 6;

  // Wildcard policy if any for the route.
  // Currently only 'Subdomain' or 'None' is allowed.
  optional string wildcardPolicy = 7;
}

// RouteStatus provides relevant info about the status of a route, including which routers
// acknowledge it.
message RouteStatus {
  // ingress describes the places where the route may be exposed. The list of
  // ingress points may contain duplicate Host or RouterName values. Routes
  // are considered live once they are `Ready`
  repeated RouteIngress ingress = 1;
}

// RouteTargetReference specifies the target that resolve into endpoints. Only the 'Service'
// kind is allowed. Use 'weight' field to emphasize one over others.
message RouteTargetReference {
  // The kind of target that the route is referring to. Currently, only 'Service' is allowed
  optional string kind = 1;

  // name of the service/target that is being referred to. e.g. name of the service
  optional string name = 2;

  // weight as an integer between 0 and 256, default 1, that specifies the target's relative weight
  // against other target reference objects. 0 suppresses requests to this backend.
  optional int32 weight = 3;
}

// RouterShard has information of a routing shard and is used to
// generate host names and routing table entries when a routing shard is
// allocated for a specific route.
// Caveat: This is WIP and will likely undergo modifications when sharding
//         support is added.
message RouterShard {
  // shardName uniquely identifies a router shard in the "set" of
  // routers used for routing traffic to the services.
  optional string shardName = 1;

  // dnsSuffix for the shard ala: shard-1.v3.openshift.com
  optional string dnsSuffix = 2;
}

// TLSConfig defines config used to secure a route and provide termination
message TLSConfig {
  // termination indicates termination type.
  optional string termination = 1;

  // certificate provides certificate contents
  optional string certificate = 2;

  // key provides key file contents
  optional string key = 3;

  // caCertificate provides the cert authority certificate contents
  optional string caCertificate = 4;

  // destinationCACertificate provides the contents of the ca certificate of the final destination.  When using reencrypt
  // termination this file should be provided in order to have routers use it for health checks on the secure connection.
  // If this field is not specified, the router may provide its own destination CA and perform hostname validation using
  // the short service name (service.namespace.svc), which allows infrastructure generated certificates to automatically
  // verify.
  optional string destinationCACertificate = 5;

  // insecureEdgeTerminationPolicy indicates the desired behavior for insecure connections to a route. While
  // each router may make its own decisions on which ports to expose, this is normally port 80.
  // 
  // * Allow - traffic is sent to the server on the insecure port (default)
  // * Disable - no traffic is allowed on the insecure port.
  // * Redirect - clients are redirected to the secure port.
  optional string insecureEdgeTerminationPolicy = 6;
}