docs/index.html



<!doctype html>
<html lang="en" class="no-js">
  <head>
    
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width,initial-scale=1">
      <meta http-equiv="x-ua-compatible" content="ie=edge">
      
      
        <meta name="lang:clipboard.copy" content="Copy to clipboard">
      
        <meta name="lang:clipboard.copied" content="Copied to clipboard">
      
        <meta name="lang:search.language" content="en">
      
        <meta name="lang:search.pipeline.stopwords" content="True">
      
        <meta name="lang:search.pipeline.trimmer" content="True">
      
        <meta name="lang:search.result.none" content="No matching documents">
      
        <meta name="lang:search.result.one" content="1 matching document">
      
        <meta name="lang:search.result.other" content="# matching documents">
      
        <meta name="lang:search.tokenizer" content="[\s\-]+">
      
      <link rel="shortcut icon" href="assets/images/favicon.png">
      <meta name="generator" content="mkdocs-1.0.4, mkdocs-material-4.6.0">
    
    
        <title>Kubernetes Service APIs</title>
      
    
      <link rel="stylesheet" href="assets/stylesheets/application.1b62728e.css">
      
      
      <script src="assets/javascripts/modernizr.268332fc.js"></script>
    
    
        <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>
        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700%7CRoboto+Mono&display=fallback">
        <style>body,input{font-family:"Roboto","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono","Courier New",Courier,monospace}</style>
      
    
    <link rel="stylesheet" href="assets/fonts/material-icons.css">
    
    
  </head>
  
    <body dir="ltr">
  
    <svg class="md-svg">
      <defs>
        
        
      </defs>
    </svg>
    <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
    <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
    <label class="md-overlay" data-md-component="overlay" for="__drawer"></label>
    
      <a href="#introduction" tabindex="1" class="md-skip">
        Skip to content
      </a>
    
    
      <header class="md-header" data-md-component="header">
  <nav class="md-header-nav md-grid">
    <div class="md-flex">
      <div class="md-flex__cell md-flex__cell--shrink">
        <a href="." title="Kubernetes Service APIs" class="md-header-nav__button md-logo">
          
            <i class="md-icon"></i>
          
        </a>
      </div>
      <div class="md-flex__cell md-flex__cell--shrink">
        <label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
      </div>
      <div class="md-flex__cell md-flex__cell--stretch">
        <div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
          
            <span class="md-header-nav__topic">
              Kubernetes Service APIs
            </span>
            <span class="md-header-nav__topic">
              
                Introduction
              
            </span>
          
        </div>
      </div>
      <div class="md-flex__cell md-flex__cell--shrink">
        
      </div>
      
        <div class="md-flex__cell md-flex__cell--shrink">
          <div class="md-header-nav__source">
            

<a href="http://sigs.k8s.io/service-apis" title="Go to repository" class="md-source" data-md-source="">
  
  <div class="md-source__repository">
    GitHub
  </div>
</a>
          </div>
        </div>
      
    </div>
  </nav>
</header>
    
    <div class="md-container">
      
        
      <main class="md-main" role="main">
        <div class="md-main__inner md-grid" data-md-component="container">
          
            
              <div class="md-sidebar md-sidebar--primary" data-md-component="navigation">
                <div class="md-sidebar__scrollwrap">
                  <div class="md-sidebar__inner">
                    <nav class="md-nav md-nav--primary" data-md-level="0">
  <label class="md-nav__title md-nav__title--site" for="__drawer">
    <a href="." title="Kubernetes Service APIs" class="md-nav__button md-logo">
      
        <i class="md-icon"></i>
      
    </a>
    Kubernetes Service APIs
  </label>
  
    <div class="md-nav__source">
      

<a href="http://sigs.k8s.io/service-apis" title="Go to repository" class="md-source" data-md-source="">
  
  <div class="md-source__repository">
    GitHub
  </div>
</a>
    </div>
  
  <ul class="md-nav__list" data-md-scrollfix>
    
      
  <li class="md-nav__item md-nav__item--active">
    
    <input class="md-toggle md-nav__toggle" data-md-toggle="toc" type="checkbox" id="__toc">
    
      
      <label class="md-nav__link md-nav__link--active" for="__toc">
        Introduction
      </label>
    
    <a href="." title="Introduction" class="md-nav__link md-nav__link--active">
      Introduction
    </a>
    
      
<nav class="md-nav md-nav--secondary">
  
  
    <label class="md-nav__title" for="__toc">Table of contents</label>
    <ul class="md-nav__list" data-md-scrollfix>
      
        <li class="md-nav__item">
  <a href="#what-is-the-goal-of-service-apis" class="md-nav__link">
    What is the goal of Service APIs?
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#where-to-get-started" class="md-nav__link">
    Where to get started
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#how-to-get-involved" class="md-nav__link">
    How to get involved
  </a>
  
</li>
      
      
    </ul>
  
</nav>
    
  </li>

    
  <li class="md-nav__item md-nav__item--nested">
    
      <input class="md-toggle md-nav__toggle" data-md-toggle="nav-2" type="checkbox" id="nav-2">
    
    <label class="md-nav__link" for="nav-2">
      Concepts
    </label>
    <nav class="md-nav" data-md-component="collapsible" data-md-level="1">
      <label class="md-nav__title" for="nav-2">
        Concepts
      </label>
      <ul class="md-nav__list" data-md-scrollfix>
        
        
  <li class="md-nav__item">
    <a href="api-overview/" title="API overview" class="md-nav__link">
      API overview
    </a>
  </li>

        
  <li class="md-nav__item">
    <a href="security-model/" title="Security Model" class="md-nav__link">
      Security Model
    </a>
  </li>

        
  <li class="md-nav__item">
    <a href="guidelines/" title="Implementation Guidelines" class="md-nav__link">
      Implementation Guidelines
    </a>
  </li>

        
      </ul>
    </nav>
  </li>

    
  <li class="md-nav__item md-nav__item--nested">
    
      <input class="md-toggle md-nav__toggle" data-md-toggle="nav-3" type="checkbox" id="nav-3">
    
    <label class="md-nav__link" for="nav-3">
      API Types
    </label>
    <nav class="md-nav" data-md-component="collapsible" data-md-level="1">
      <label class="md-nav__title" for="nav-3">
        API Types
      </label>
      <ul class="md-nav__list" data-md-scrollfix>
        
        
  <li class="md-nav__item">
    <a href="gatewayclass/" title="GatewayClass" class="md-nav__link">
      GatewayClass
    </a>
  </li>

        
  <li class="md-nav__item">
    <a href="gateway/" title="Gateway" class="md-nav__link">
      Gateway
    </a>
  </li>

        
  <li class="md-nav__item">
    <a href="httproute/" title="HTTPRoute" class="md-nav__link">
      HTTPRoute
    </a>
  </li>

        
      </ul>
    </nav>
  </li>

    
  <li class="md-nav__item md-nav__item--nested">
    
      <input class="md-toggle md-nav__toggle" data-md-toggle="nav-4" type="checkbox" id="nav-4">
    
    <label class="md-nav__link" for="nav-4">
      Guides
    </label>
    <nav class="md-nav" data-md-component="collapsible" data-md-level="1">
      <label class="md-nav__title" for="nav-4">
        Guides
      </label>
      <ul class="md-nav__list" data-md-scrollfix>
        
        
  <li class="md-nav__item">
    <a href="guides/" title="Introduction" class="md-nav__link">
      Introduction
    </a>
  </li>

        
  <li class="md-nav__item">
    <a href="getting-started/" title="Getting started" class="md-nav__link">
      Getting started
    </a>
  </li>

        
  <li class="md-nav__item">
    <a href="simple-gateway/" title="Simple Gateway" class="md-nav__link">
      Simple Gateway
    </a>
  </li>

        
  <li class="md-nav__item">
    <a href="http-routing/" title="HTTP routing" class="md-nav__link">
      HTTP routing
    </a>
  </li>

        
  <li class="md-nav__item">
    <a href="multiple-ns/" title="Multiple namespaces and routes" class="md-nav__link">
      Multiple namespaces and routes
    </a>
  </li>

        
  <li class="md-nav__item">
    <a href="tls/" title="TLS" class="md-nav__link">
      TLS
    </a>
  </li>

        
  <li class="md-nav__item">
    <a href="tcp/" title="TCP routing" class="md-nav__link">
      TCP routing
    </a>
  </li>

        
      </ul>
    </nav>
  </li>

    
  <li class="md-nav__item md-nav__item--nested">
    
      <input class="md-toggle md-nav__toggle" data-md-toggle="nav-5" type="checkbox" id="nav-5">
    
    <label class="md-nav__link" for="nav-5">
      References
    </label>
    <nav class="md-nav" data-md-component="collapsible" data-md-level="1">
      <label class="md-nav__title" for="nav-5">
        References
      </label>
      <ul class="md-nav__list" data-md-scrollfix>
        
        
  <li class="md-nav__item">
    <a href="spec/" title="API specification" class="md-nav__link">
      API specification
    </a>
  </li>

        
  <li class="md-nav__item">
    <a href="releases/" title="Releases" class="md-nav__link">
      Releases
    </a>
  </li>

        
      </ul>
    </nav>
  </li>

    
  <li class="md-nav__item md-nav__item--nested">
    
      <input class="md-toggle md-nav__toggle" data-md-toggle="nav-6" type="checkbox" id="nav-6">
    
    <label class="md-nav__link" for="nav-6">
      Contributing
    </label>
    <nav class="md-nav" data-md-component="collapsible" data-md-level="1">
      <label class="md-nav__title" for="nav-6">
        Contributing
      </label>
      <ul class="md-nav__list" data-md-scrollfix>
        
        
  <li class="md-nav__item">
    <a href="devguide/" title="Developer guide" class="md-nav__link">
      Developer guide
    </a>
  </li>

        
  <li class="md-nav__item">
    <a href="enhancement-requests/" title="Enhancement requests" class="md-nav__link">
      Enhancement requests
    </a>
  </li>

        
  <li class="md-nav__item">
    <a href="community/" title="Community" class="md-nav__link">
      Community
    </a>
  </li>

        
      </ul>
    </nav>
  </li>

    
  <li class="md-nav__item">
    <a href="faq/" title="FAQ" class="md-nav__link">
      FAQ
    </a>
  </li>

    
  </ul>
</nav>
                  </div>
                </div>
              </div>
            
            
              <div class="md-sidebar md-sidebar--secondary" data-md-component="toc">
                <div class="md-sidebar__scrollwrap">
                  <div class="md-sidebar__inner">
                    
<nav class="md-nav md-nav--secondary">
  
  
    <label class="md-nav__title" for="__toc">Table of contents</label>
    <ul class="md-nav__list" data-md-scrollfix>
      
        <li class="md-nav__item">
  <a href="#what-is-the-goal-of-service-apis" class="md-nav__link">
    What is the goal of Service APIs?
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#where-to-get-started" class="md-nav__link">
    Where to get started
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#how-to-get-involved" class="md-nav__link">
    How to get involved
  </a>
  
</li>
      
      
    </ul>
  
</nav>
                  </div>
                </div>
              </div>
            
          
          <div class="md-content">
            <article class="md-content__inner md-typeset">
              
                
                <h1 id="introduction">Introduction</h1>
<p>Service APIs is an open source project managed by the <a href="https://github.com/kubernetes/community/tree/master/sig-network">SIG-NETWORK</a>
community. The project's goal is to evolve service networking APIs within the
Kubernetes ecosystem. Service APIs provide interfaces to expose Kubernetes
applications - Services, Ingress, and more. </p>
<h3 id="what-is-the-goal-of-service-apis">What is the goal of Service APIs?</h3>
<p>Service APIs aims to improve service networking by providing expressive,
extensible, role-oriented interfaces that are implemented by many vendors and
have broad industry support. </p>
<p>Service APIs is a collection of API resources - <code>Service</code>, <code>GatewayClass</code>,
<code>Gateway</code>, <code>HTTPRoute</code>, <code>TCPRoute</code>, etc. Together these resources model a wide
variety of networking use-cases.</p>
<p><img alt="Service API Model" src="images/api-model.png" /></p>
<p>How do Service APIs improve upon current standards like Ingress?</p>
<ul>
<li><strong>More expressive</strong> - They express more core functionality for things like
header-based matching, traffic weighting, and other capabilities that were only
possible in Ingress through custom means.    </li>
<li><strong>More extensible</strong> - They allow for custom resources to be linked at various
layers of the API. This allows for more granular customization at the
appropriate places within the API structure.</li>
<li><strong>Role oriented</strong> - They are separated into different API resources that map
to the common roles for running applications on Kubernetes.    </li>
<li><strong>Generic</strong> - This isn't an improvement but rather something
that should stay the same. Just as Ingress is a universal specification with
<a href="https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/">numerous implementations</a>,
Service APIs are designed to be a portable specification supported by many
implementations.</li>
</ul>
<p>Some other notable capabilities include …</p>
<ul>
<li><strong>Shared Gateways</strong> - They allow the sharing of load balancers and VIPs by
permitting independent Route resources to bind to the same Gateway. This allows
teams to share infrastructure safely without requiring direct coordination.  </li>
<li><strong>Typed backend references</strong> - With typed backend references Routes can
reference Kubernetes Services, but also any kind of Kubernetes resource that is
designed to be a Gateway backend.  </li>
<li><strong>Cross-Namespace references</strong> - Routes across different Namespaces can bind<br />
to Gateways. This allows for shared networking infrastructure despite Namespace<br />
segmentation for workloads.  </li>
<li><strong>Classes</strong> - GatewayClasses formalize types of load balancing implementations. 
These classes make it easy and explicit for users to understand what kind of
capabilities are available as a resource model itself.</li>
</ul>
<h3 id="where-to-get-started">Where to get started</h3>
<p>To get started, please read through <a href="api-overview/">API overview</a>. These
documents give the necessary background to understand the API and the use-cases
it targets. Once you have a good understanding of the API at a higher-level,
please follow one of our <a href="guides/">guides</a> to dive deeper into different parts
of the API.</p>
<p>For a complete API reference, please refer to:</p>
<ul>
<li><a href="spec/">API reference</a> </li>
<li><a href="https://pkg.go.dev/sigs.k8s.io/service-apis/apis/v1alpha1">Go docs for the package</a></li>
</ul>
<h3 id="how-to-get-involved">How to get involved</h3>
<p>This project has many contributors, and we welcome anybody and everybody to get
involved. Join our weekly meetings, file issues, or ask questions in Slack. No
contribution is too small - even opinions matter! </p>
<ul>
<li><a href="community/#meetings">Weekly meeting schedule</a> </li>
<li><a href="https://kubernetes.slack.com/messages/sig-network-service-apis">Service APIs Slack</a> </li>
<li><a href="enhancement-requests/">Enhancement requests</a>  </li>
<li><a href="https://raw.githubusercontent.com/kubernetes-sigs/service-apis/master/OWNERS">Project owners</a></li>
</ul>
                
                  
            </article>
          </div>
        </div>
      </main>
      
        
<footer class="md-footer">
  
    <div class="md-footer-nav">
      <nav class="md-footer-nav__inner md-grid">
        
        
          <a href="api-overview/" title="API overview" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next">
            <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
              <span class="md-flex__ellipsis">
                <span class="md-footer-nav__direction">
                  Next
                </span>
                API overview
              </span>
            </div>
            <div class="md-flex__cell md-flex__cell--shrink">
              <i class="md-icon md-icon--arrow-forward md-footer-nav__button"></i>
            </div>
          </a>
        
      </nav>
    </div>
  
  <div class="md-footer-meta md-typeset">
    <div class="md-footer-meta__inner md-grid">
      <div class="md-footer-copyright">
        
        powered by
        <a href="https://www.mkdocs.org">MkDocs</a>
        and
        <a href="https://squidfunk.github.io/mkdocs-material/">
          Material for MkDocs</a>
      </div>
      
    </div>
  </div>
</footer>
      
    </div>
    
      <script src="assets/javascripts/application.808e90bb.js"></script>
      
      <script>app.initialize({version:"1.0.4",url:{base:"."}})</script>
      
    
  </body>
</html>