docs/getting-started/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>Getting started - 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="#getting-started-with-services-apis" 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">
              
                Getting started
              
            </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--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--active md-nav__item--nested">
    
      <input class="md-toggle md-nav__toggle" data-md-toggle="nav-4" type="checkbox" id="nav-4" checked>
    
    <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 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">
        Getting started
      </label>
    
    <a href="./" title="Getting started" class="md-nav__link md-nav__link--active">
      Getting started
    </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="#installing-crds" class="md-nav__link">
    Installing CRDs
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#install-an-implementation" class="md-nav__link">
    Install an implementation
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#sample-gateway" class="md-nav__link">
    Sample Gateway
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#uninstalling-the-crds" class="md-nav__link">
    Uninstalling the CRDs
  </a>
  
</li>
      
      
    </ul>
  
</nav>
    
  </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="#installing-crds" class="md-nav__link">
    Installing CRDs
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#install-an-implementation" class="md-nav__link">
    Install an implementation
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#sample-gateway" class="md-nav__link">
    Sample Gateway
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#uninstalling-the-crds" class="md-nav__link">
    Uninstalling the CRDs
  </a>
  
</li>
      
      
    </ul>
  
</nav>
                  </div>
                </div>
              </div>
            
          
          <div class="md-content">
            <article class="md-content__inner md-typeset">
              
                
                <h1 id="getting-started-with-services-apis">Getting started with Services APIs</h1>
<h2 id="installing-crds">Installing CRDs</h2>
<p>This project provides a collection of Custom Resource Definitions (CRDs) that can
be installed into any Kubernetes (&gt;= 1.16) cluster.</p>
<p>To install the CRDs, please execute:</p>
<pre><code>kubectl kustomize &quot;github.com/kubernetes-sigs/service-apis/config/crd?ref=v0.1.0&quot; \
| kubectl apply -f -
</code></pre>

<h2 id="install-an-implementation">Install an implementation</h2>
<p>Multiple projects implement the APIs defined by this project.
You will need to either install an implementation or verify that one is already
setup for your cluster.</p>
<h2 id="sample-gateway">Sample Gateway</h2>
<p>Once you have the CRDs and an implementation installed, you are ready to
use Service APIs.</p>
<p>In this example, we are installing three resources:</p>
<ul>
<li>An <code>acme-lb</code> GatewayClass which is being managed by a <code>acme.io/gateway-controller</code>
  controller running in the cluster. Typically, a GatewayClass is provided by
  the implementation and must be installed in the cluster.</li>
<li>
<p>A Gateway which is of type <code>acme-lb</code>:</p>
<ul>
<li>This gateway has a single HTTP listener on port 80 which selects HTTPRoutes
  from all namespaces which have the label <code>app: foo</code> on them.</li>
</ul>
</li>
<li>
<p>Finally, we have an HTTPRoute resource which is attached to the above Gateway
  and has two rules:</p>
<ul>
<li>All requests with path beginning with <code>/bar</code> are forwarded to my-service1
  Kubernetes Service.</li>
<li>All requests with path beginning with <code>/some/thing</code> AND have an HTTP header
  <code>magic: foo</code> are forwarded to my-service2 Kubernetes Service.</li>
</ul>
</li>
</ul>
<p>With this configuration, you now have a Gateway resource which is forwarding
traffic to two Kubernetes Services based on HTTP request metadata.</p>
<pre><code>kind: GatewayClass
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
  name: acme-lb
spec:
  controller: acme.io/gateway-controller
  parametersRef:
    name: acme-lb
    group: acme.io
    kind: Parameters
---
kind: Gateway
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
  name: my-gateway
spec:
  gatewayClassName: acme-lb
  listeners:  # Use GatewayClass defaults for listener definition.
  - protocol: HTTP
    port: 80
    routes:
      kind: HTTPRoute
      selector:
        matchLabels:
          app: foo
      namespaces:
        from: &quot;Same&quot;
---
kind: HTTPRoute
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
  name: http-app-1
  labels:
    app: foo
spec:
  hostnames:
  - &quot;foo.com&quot;
  rules:
  - matches:
    - path:
        type: Prefix
        value: /bar
    forwardTo:
    - serviceName: my-service1
      port: 8080
  - matches:
    - headers:
        type: Exact
        values:
          magic: foo
      path:
        type: Prefix
        value: /some/thing
    forwardTo:
    - serviceName: my-service2
      port: 8080
</code></pre>

<p>For more advanced examples, please read the other <a href="../guides/">guides</a>.</p>
<h2 id="uninstalling-the-crds">Uninstalling the CRDs</h2>
<p>To uninstall the CRDs and all resources created with them, run the following
command. Note that this will remove all GatewayClass and Gateway resources in
your cluster. If you have been using these resources for any other purpose do
not uninstall these CRDs.</p>
<pre><code>kubectl kustomize &quot;github.com/kubernetes-sigs/service-apis/config/crd?ref=v0.1.0&quot; \
| kubectl delete -f -
</code></pre>
                
                  
            </article>
          </div>
        </div>
      </main>
      
        
<footer class="md-footer">
  
    <div class="md-footer-nav">
      <nav class="md-footer-nav__inner md-grid">
        
          <a href="../guides/" title="Introduction" 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>
                Introduction
              </span>
            </div>
          </a>
        
        
          <a href="../simple-gateway/" title="Simple Gateway" 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>
                Simple Gateway
              </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>