docs/guidelines/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>Implementation Guidelines - 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="#implementation-guidelines" 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">
              
                Implementation Guidelines
              
            </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">
    <a href=".." title="Introduction" class="md-nav__link">
      Introduction
    </a>
  </li>

    
  <li class="md-nav__item md-nav__item--active md-nav__item--nested">
    
      <input class="md-toggle md-nav__toggle" data-md-toggle="nav-2" type="checkbox" id="nav-2" checked>
    
    <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 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">
        Implementation Guidelines
      </label>
    
    <a href="./" title="Implementation Guidelines" class="md-nav__link md-nav__link--active">
      Implementation Guidelines
    </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="#single-resource-consistency" class="md-nav__link">
    Single resource consistency
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#conflicts" class="md-nav__link">
    Conflicts
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#conformance" class="md-nav__link">
    Conformance
  </a>
  
    <nav class="md-nav">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#conformance-expectations" class="md-nav__link">
    Conformance expectations
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
      
      
    </ul>
  
</nav>
    
  </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="../traffic-splitting/" title="HTTP traffic splitting" class="md-nav__link">
      HTTP traffic splitting
    </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="#single-resource-consistency" class="md-nav__link">
    Single resource consistency
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#conflicts" class="md-nav__link">
    Conflicts
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#conformance" class="md-nav__link">
    Conformance
  </a>
  
    <nav class="md-nav">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#conformance-expectations" class="md-nav__link">
    Conformance expectations
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
      
      
    </ul>
  
</nav>
                  </div>
                </div>
              </div>
            
          
          <div class="md-content">
            <article class="md-content__inner md-typeset">
              
                
                <h1 id="implementation-guidelines">Implementation guidelines</h1>
<p>There are some general design guidelines used throughout this API.</p>
<h2 id="single-resource-consistency">Single resource consistency</h2>
<p>The Kubernetes API guarantees consistency only on a single resource level. There
are a couple of consequences for complex resource graphs as opposed to single
resources:</p>
<ul>
<li>Error checking of properties spanning multiple resource will be asynchronous
    and eventually consistent. Simple syntax checks will be possible at the
    single resource level, but cross resource dependencies will need to be
    handled by the controller.</li>
<li>Controllers will need to handle broken links between resources and/or
    mismatched configuration.</li>
</ul>
<h2 id="conflicts">Conflicts</h2>
<p>Separation and delegation of responsibility among independent actors (e.g
between cluster ops and application developers) can result in conflicts in the
configuration. For example, two application teams may inadvertently submit
configuration for the same HTTP path.</p>
<p>In most cases, guidance for conflict resolution is provided along with the
documentation for fields that may have a conflict. If a conflict does not have a
prescribed resolution, the following guiding principles should be applied:</p>
<ul>
<li>Prefer not to break things that are working.</li>
<li>Drop as little traffic as possible.</li>
<li>Provide a consistent experience when conflicts occur.</li>
<li>Make it clear which path has been chosen when a conflict has been identified.
  Where possible, this should be communicated by setting appropriate status
  conditions on relevant resources.</li>
<li>More specific matches should be given precedence over less specific ones.</li>
<li>The resource with the oldest creation timestamp wins.</li>
<li>If everything else is equivalent (including creation timestamp), precedences
  should be given to the resource appearing first in alphabetical order
  (namespace/name). For example, foo/bar would be given precedence over foo/baz.</li>
</ul>
<h2 id="conformance">Conformance</h2>
<p>As this API aims to cover a wide set of implementations and use cases,
it will not be possible for all implementations to support <em>all</em>
features at the present. However, we do expect the set of features
supported to converge eventually. For a given feature, users will be
guaranteed that features in the API will be portable between providers
if the feature is supported.</p>
<p>To model this in the API, we are taking a similar approach as with
<a href="https://github.com/kubernetes/enhancements/tree/master/keps/sig-architecture/960-conformance-behaviors">sig-arch</a> work on conformance profiles. Features as
described in the API spec will be divided into three major categories:</p>
<ul>
<li><strong>CORE</strong> features will be portable and we expect that there is a
  reasonable roadmap for ALL implementations towards support of APIs
  in this category.</li>
<li><strong>EXTENDED</strong> features are those that are portable but not
  universally supported across implementations. Those implementations
  that support the feature will have the same behavior and
  semantics. It is expected that some number of EXTENDED features will
  eventually migrate into the CORE. EXTENDED features will be part of
  the API types and schema.</li>
<li><strong>CUSTOM</strong> features are those that are not portable and are
  vendor-specific. CUSTOM features will not have API types and schema
  except via generic extension points.</li>
</ul>
<p>Behavior and feature in the CORE and EXTENDED set will be defined and
validated via behavior-driven conformance tests. CUSTOM features will
not be covered by conformance tests.</p>
<p>By including and standardizing EXTENDED features in the API spec, we
expect to be able to converge on portable subsets of the API among
implementations without compromising overall API support. Lack of
universal support will not be a blocker towards developing portable
feature sets. Standardizing on spec will make it easier to eventually
graduate to CORE when support is widespread.</p>
<h3 id="conformance-expectations">Conformance expectations</h3>
<p>We expect there will be varying levels of conformance among the
different providers in the early days of this API. Users can use the
results of the conformance tests to understand areas where there may
be differences in behavior from the spec.</p>
                
                  
            </article>
          </div>
        </div>
      </main>
      
        
<footer class="md-footer">
  
    <div class="md-footer-nav">
      <nav class="md-footer-nav__inner md-grid">
        
          <a href="../security-model/" title="Security Model" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev">
            <div class="md-flex__cell md-flex__cell--shrink">
              <i class="md-icon md-icon--arrow-back md-footer-nav__button"></i>
            </div>
            <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
              <span class="md-flex__ellipsis">
                <span class="md-footer-nav__direction">
                  Previous
                </span>
                Security Model
              </span>
            </div>
          </a>
        
        
          <a href="../gatewayclass/" title="GatewayClass" 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>
                GatewayClass
              </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>