2464 lines
93 KiB
HTML
2464 lines
93 KiB
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-3.0.4">
|
|
|
|
|
|
|
|
<title>Annotations - NGINX Ingress Controller</title>
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="../../../assets/stylesheets/application.451f80e5.css">
|
|
|
|
<link rel="stylesheet" href="../../../assets/stylesheets/application-palette.22915126.css">
|
|
|
|
|
|
|
|
|
|
<meta name="theme-color" content="#009688">
|
|
|
|
|
|
|
|
<script src="../../../assets/javascripts/modernizr.1aa3b519.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|Roboto+Mono">
|
|
<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">
|
|
|
|
<link rel="stylesheet" href="../../../extra.css">
|
|
|
|
|
|
</head>
|
|
|
|
|
|
|
|
<body dir="ltr" data-md-color-primary="teal" data-md-color-accent="green">
|
|
|
|
<svg class="md-svg">
|
|
<defs>
|
|
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" width="416" height="448"
|
|
viewBox="0 0 416 448" id="__github">
|
|
<path fill="currentColor" d="M160 304q0 10-3.125 20.5t-10.75 19-18.125
|
|
8.5-18.125-8.5-10.75-19-3.125-20.5 3.125-20.5 10.75-19 18.125-8.5
|
|
18.125 8.5 10.75 19 3.125 20.5zM320 304q0 10-3.125 20.5t-10.75
|
|
19-18.125 8.5-18.125-8.5-10.75-19-3.125-20.5 3.125-20.5 10.75-19
|
|
18.125-8.5 18.125 8.5 10.75 19 3.125 20.5zM360
|
|
304q0-30-17.25-51t-46.75-21q-10.25 0-48.75 5.25-17.75 2.75-39.25
|
|
2.75t-39.25-2.75q-38-5.25-48.75-5.25-29.5 0-46.75 21t-17.25 51q0 22 8
|
|
38.375t20.25 25.75 30.5 15 35 7.375 37.25 1.75h42q20.5 0
|
|
37.25-1.75t35-7.375 30.5-15 20.25-25.75 8-38.375zM416 260q0 51.75-15.25
|
|
82.75-9.5 19.25-26.375 33.25t-35.25 21.5-42.5 11.875-42.875 5.5-41.75
|
|
1.125q-19.5 0-35.5-0.75t-36.875-3.125-38.125-7.5-34.25-12.875-30.25-20.25-21.5-28.75q-15.5-30.75-15.5-82.75
|
|
0-59.25 34-99-6.75-20.5-6.75-42.5 0-29 12.75-54.5 27 0 47.5 9.875t47.25
|
|
30.875q36.75-8.75 77.25-8.75 37 0 70 8 26.25-20.5
|
|
46.75-30.25t47.25-9.75q12.75 25.5 12.75 54.5 0 21.75-6.75 42 34 40 34
|
|
99.5z" />
|
|
</svg>
|
|
|
|
</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="../../../#annotations" 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="NGINX Ingress Controller" class="md-header-nav__button md-logo">
|
|
|
|
<i class="md-icon">public</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">
|
|
NGINX Ingress Controller
|
|
</span>
|
|
<span class="md-header-nav__topic">
|
|
Annotations
|
|
</span>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
<div class="md-flex__cell md-flex__cell--shrink">
|
|
|
|
|
|
<label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
|
|
|
|
<div class="md-search" data-md-component="search" role="dialog">
|
|
<label class="md-search__overlay" for="__search"></label>
|
|
<div class="md-search__inner" role="search">
|
|
<form class="md-search__form" name="search">
|
|
<input type="text" class="md-search__input" name="query" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="query" data-md-state="active">
|
|
<label class="md-icon md-search__icon" for="__search"></label>
|
|
<button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1">
|
|

|
|
</button>
|
|
</form>
|
|
<div class="md-search__output">
|
|
<div class="md-search__scrollwrap" data-md-scrollfix>
|
|
<div class="md-search-result" data-md-component="result">
|
|
<div class="md-search-result__meta">
|
|
Type to start searching
|
|
</div>
|
|
<ol class="md-search-result__list"></ol>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
<div class="md-flex__cell md-flex__cell--shrink">
|
|
<div class="md-header-nav__source">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://github.com/kubernetes/ingress-nginx/" title="Go to repository" class="md-source" data-md-source="github">
|
|
|
|
<div class="md-source__icon">
|
|
<svg viewBox="0 0 24 24" width="24" height="24">
|
|
<use xlink:href="#__github" width="24" height="24"></use>
|
|
</svg>
|
|
</div>
|
|
|
|
<div class="md-source__repository">
|
|
kubernetes/ingress-nginx
|
|
</div>
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
</nav>
|
|
</header>
|
|
|
|
<div class="md-container">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<nav class="md-tabs md-tabs--active" data-md-component="tabs">
|
|
<div class="md-tabs__inner md-grid">
|
|
<ul class="md-tabs__list">
|
|
|
|
|
|
|
|
|
|
<li class="md-tabs__item">
|
|
|
|
<a href="../../.." title="Welcome" class="md-tabs__link">
|
|
Welcome
|
|
</a>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-tabs__item">
|
|
|
|
<a href="../../../deploy/" title="Deployment" class="md-tabs__link">
|
|
Deployment
|
|
</a>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-tabs__item">
|
|
|
|
<a href="../" title="User guide" class="md-tabs__link md-tabs__link--active">
|
|
User guide
|
|
</a>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-tabs__item">
|
|
|
|
<a href="../../../examples/" title="Examples" class="md-tabs__link">
|
|
Examples
|
|
</a>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
</ul>
|
|
</div>
|
|
</nav>
|
|
|
|
<main class="md-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="NGINX Ingress Controller" class="md-nav__button md-logo">
|
|
|
|
<i class="md-icon">public</i>
|
|
|
|
</a>
|
|
NGINX Ingress Controller
|
|
</label>
|
|
|
|
<div class="md-nav__source">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<a href="https://github.com/kubernetes/ingress-nginx/" title="Go to repository" class="md-source" data-md-source="github">
|
|
|
|
<div class="md-source__icon">
|
|
<svg viewBox="0 0 24 24" width="24" height="24">
|
|
<use xlink:href="#__github" width="24" height="24"></use>
|
|
</svg>
|
|
</div>
|
|
|
|
<div class="md-source__repository">
|
|
kubernetes/ingress-nginx
|
|
</div>
|
|
</a>
|
|
|
|
</div>
|
|
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item md-nav__item--nested">
|
|
|
|
<input class="md-toggle md-nav__toggle" data-md-toggle="nav-1" type="checkbox" id="nav-1">
|
|
|
|
<label class="md-nav__link" for="nav-1">
|
|
Welcome
|
|
</label>
|
|
<nav class="md-nav" data-md-component="collapsible" data-md-level="1">
|
|
<label class="md-nav__title" for="nav-1">
|
|
Welcome
|
|
</label>
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../.." title="Welcome" class="md-nav__link">
|
|
Welcome
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../how-it-works/" title="How it works" class="md-nav__link">
|
|
How it works
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../troubleshooting/" title="Troubleshooting" class="md-nav__link">
|
|
Troubleshooting
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../development/" title="Development" class="md-nav__link">
|
|
Development
|
|
</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">
|
|
Deployment
|
|
</label>
|
|
<nav class="md-nav" data-md-component="collapsible" data-md-level="1">
|
|
<label class="md-nav__title" for="nav-2">
|
|
Deployment
|
|
</label>
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../deploy/" title="Installation Guide" class="md-nav__link">
|
|
Installation Guide
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../deploy/baremetal/" title="Bare-metal considerations" class="md-nav__link">
|
|
Bare-metal considerations
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../deploy/rbac/" title="Role Based Access Control (RBAC)" class="md-nav__link">
|
|
Role Based Access Control (RBAC)
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../deploy/upgrade/" title="Upgrade" class="md-nav__link">
|
|
Upgrade
|
|
</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-3" type="checkbox" id="nav-3" checked>
|
|
|
|
<label class="md-nav__link" for="nav-3">
|
|
User guide
|
|
</label>
|
|
<nav class="md-nav" data-md-component="collapsible" data-md-level="1">
|
|
<label class="md-nav__title" for="nav-3">
|
|
User guide
|
|
</label>
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item md-nav__item--active md-nav__item--nested">
|
|
|
|
<input class="md-toggle md-nav__toggle" data-md-toggle="nav-3-1" type="checkbox" id="nav-3-1" checked>
|
|
|
|
<label class="md-nav__link" for="nav-3-1">
|
|
NGINX Configuration
|
|
</label>
|
|
<nav class="md-nav" data-md-component="collapsible" data-md-level="2">
|
|
<label class="md-nav__title" for="nav-3-1">
|
|
NGINX Configuration
|
|
</label>
|
|
<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">
|
|
|
|
<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">
|
|
Annotations
|
|
</label>
|
|
|
|
<a href="./" title="Annotations" class="md-nav__link md-nav__link--active">
|
|
Annotations
|
|
</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="#rewrite" title="Rewrite" class="md-nav__link">
|
|
Rewrite
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#session-affinity" title="Session Affinity" class="md-nav__link">
|
|
Session Affinity
|
|
</a>
|
|
|
|
<nav class="md-nav">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#cookie-affinity" title="Cookie affinity" class="md-nav__link">
|
|
Cookie affinity
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#authentication" title="Authentication" class="md-nav__link">
|
|
Authentication
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#custom-nginx-upstream-hashing" title="Custom NGINX upstream hashing" class="md-nav__link">
|
|
Custom NGINX upstream hashing
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#custom-nginx-load-balancing" title="Custom NGINX load balancing" class="md-nav__link">
|
|
Custom NGINX load balancing
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#custom-nginx-upstream-vhost" title="Custom NGINX upstream vhost" class="md-nav__link">
|
|
Custom NGINX upstream vhost
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#client-certificate-authentication" title="Client Certificate Authentication" class="md-nav__link">
|
|
Client Certificate Authentication
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#configuration-snippet" title="Configuration snippet" class="md-nav__link">
|
|
Configuration snippet
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#default-backend" title="Default Backend" class="md-nav__link">
|
|
Default Backend
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#enable-cors" title="Enable CORS" class="md-nav__link">
|
|
Enable CORS
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#server-alias" title="Server Alias" class="md-nav__link">
|
|
Server Alias
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#server-snippet" title="Server snippet" class="md-nav__link">
|
|
Server snippet
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#client-body-buffer-size" title="Client Body Buffer Size" class="md-nav__link">
|
|
Client Body Buffer Size
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#external-authentication" title="External Authentication" class="md-nav__link">
|
|
External Authentication
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#rate-limiting" title="Rate limiting" class="md-nav__link">
|
|
Rate limiting
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#permanent-redirect" title="Permanent Redirect" class="md-nav__link">
|
|
Permanent Redirect
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#permanent-redirect-code" title="Permanent Redirect Code" class="md-nav__link">
|
|
Permanent Redirect Code
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#ssl-passthrough" title="SSL Passthrough" class="md-nav__link">
|
|
SSL Passthrough
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#service-upstream" title="Service Upstream" class="md-nav__link">
|
|
Service Upstream
|
|
</a>
|
|
|
|
<nav class="md-nav">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#known-issues" title="Known Issues" class="md-nav__link">
|
|
Known Issues
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#server-side-https-enforcement-through-redirect" title="Server-side HTTPS enforcement through redirect" class="md-nav__link">
|
|
Server-side HTTPS enforcement through redirect
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#redirect-fromto-www" title="Redirect from/to www." class="md-nav__link">
|
|
Redirect from/to www.
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#whitelist-source-range" title="Whitelist source range" class="md-nav__link">
|
|
Whitelist source range
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#custom-timeouts" title="Custom timeouts" class="md-nav__link">
|
|
Custom timeouts
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#proxy-redirect" title="Proxy redirect" class="md-nav__link">
|
|
Proxy redirect
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#custom-max-body-size" title="Custom max body size" class="md-nav__link">
|
|
Custom max body size
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#proxy-cookie-domain" title="Proxy cookie domain" class="md-nav__link">
|
|
Proxy cookie domain
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#proxy-cookie-path" title="Proxy cookie path" class="md-nav__link">
|
|
Proxy cookie path
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#proxy-buffering" title="Proxy buffering" class="md-nav__link">
|
|
Proxy buffering
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#proxy-buffer-size" title="Proxy buffer size" class="md-nav__link">
|
|
Proxy buffer size
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#ssl-ciphers" title="SSL ciphers" class="md-nav__link">
|
|
SSL ciphers
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#connection-proxy-header" title="Connection proxy header" class="md-nav__link">
|
|
Connection proxy header
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#enable-access-log" title="Enable Access Log" class="md-nav__link">
|
|
Enable Access Log
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#enable-rewrite-log" title="Enable Rewrite Log" class="md-nav__link">
|
|
Enable Rewrite Log
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#lua-resty-waf" title="Lua Resty WAF" class="md-nav__link">
|
|
Lua Resty WAF
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#influxdb" title="InfluxDB" class="md-nav__link">
|
|
InfluxDB
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#backend-protocol" title="Backend Protocol" class="md-nav__link">
|
|
Backend Protocol
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#use-regex" title="Use Regex" class="md-nav__link">
|
|
Use Regex
|
|
</a>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
</ul>
|
|
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../configmap/" title="ConfigMap" class="md-nav__link">
|
|
ConfigMap
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../custom-template/" title="Custom NGINX template" class="md-nav__link">
|
|
Custom NGINX template
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../log-format/" title="Log format" class="md-nav__link">
|
|
Log format
|
|
</a>
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
</nav>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../cli-arguments/" title="Command line arguments" class="md-nav__link">
|
|
Command line arguments
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../custom-errors/" title="Custom errors" class="md-nav__link">
|
|
Custom errors
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../default-backend/" title="Default backend" class="md-nav__link">
|
|
Default backend
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../ingress-path-matching/" title="Regular expressions in paths" class="md-nav__link">
|
|
Regular expressions in paths
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../external-articles/" title="External Articles" class="md-nav__link">
|
|
External Articles
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../miscellaneous/" title="Miscellaneous" class="md-nav__link">
|
|
Miscellaneous
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../monitoring/" title="Prometheus and Grafana installation" class="md-nav__link">
|
|
Prometheus and Grafana installation
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../multiple-ingress/" title="Multiple Ingress controllers" class="md-nav__link">
|
|
Multiple Ingress controllers
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../tls/" title="TLS/HTTPS" class="md-nav__link">
|
|
TLS/HTTPS
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item md-nav__item--nested">
|
|
|
|
<input class="md-toggle md-nav__toggle" data-md-toggle="nav-3-11" type="checkbox" id="nav-3-11">
|
|
|
|
<label class="md-nav__link" for="nav-3-11">
|
|
Third party addons
|
|
</label>
|
|
<nav class="md-nav" data-md-component="collapsible" data-md-level="2">
|
|
<label class="md-nav__title" for="nav-3-11">
|
|
Third party addons
|
|
</label>
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../third-party-addons/modsecurity/" title="ModSecurity Web Application Firewall" class="md-nav__link">
|
|
ModSecurity Web Application Firewall
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../third-party-addons/opentracing/" title="OpenTracing" class="md-nav__link">
|
|
OpenTracing
|
|
</a>
|
|
</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-4" type="checkbox" id="nav-4">
|
|
|
|
<label class="md-nav__link" for="nav-4">
|
|
Examples
|
|
</label>
|
|
<nav class="md-nav" data-md-component="collapsible" data-md-level="1">
|
|
<label class="md-nav__title" for="nav-4">
|
|
Examples
|
|
</label>
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/" title="Introduction" class="md-nav__link">
|
|
Introduction
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/PREREQUISITES/" title="Prerequisites" class="md-nav__link">
|
|
Prerequisites
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/affinity/cookie/" title="Sticky Sessions" class="md-nav__link">
|
|
Sticky Sessions
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item md-nav__item--nested">
|
|
|
|
<input class="md-toggle md-nav__toggle" data-md-toggle="nav-4-4" type="checkbox" id="nav-4-4">
|
|
|
|
<label class="md-nav__link" for="nav-4-4">
|
|
Auth
|
|
</label>
|
|
<nav class="md-nav" data-md-component="collapsible" data-md-level="2">
|
|
<label class="md-nav__title" for="nav-4-4">
|
|
Auth
|
|
</label>
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/auth/basic/" title="Basic Authentication" class="md-nav__link">
|
|
Basic Authentication
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/auth/client-certs/" title="Client Certificate Authentication" class="md-nav__link">
|
|
Client Certificate Authentication
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/auth/external-auth/" title="External Basic Authentication" class="md-nav__link">
|
|
External Basic Authentication
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/auth/oauth-external-auth/" title="External OAUTH Authentication" class="md-nav__link">
|
|
External OAUTH Authentication
|
|
</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-5" type="checkbox" id="nav-4-5">
|
|
|
|
<label class="md-nav__link" for="nav-4-5">
|
|
Customization
|
|
</label>
|
|
<nav class="md-nav" data-md-component="collapsible" data-md-level="2">
|
|
<label class="md-nav__title" for="nav-4-5">
|
|
Customization
|
|
</label>
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/customization/configuration-snippets/" title="Configuration Snippets" class="md-nav__link">
|
|
Configuration Snippets
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/customization/custom-configuration/" title="Custom Configuration" class="md-nav__link">
|
|
Custom Configuration
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/customization/custom-errors/" title="Custom Errors" class="md-nav__link">
|
|
Custom Errors
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/customization/custom-headers/" title="Custom Headers" class="md-nav__link">
|
|
Custom Headers
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/customization/external-auth-headers/" title="External authentication" class="md-nav__link">
|
|
External authentication
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/customization/ssl-dh-param/" title="Custom DH parameters for perfect forward secrecy" class="md-nav__link">
|
|
Custom DH parameters for perfect forward secrecy
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/customization/sysctl/" title="Sysctl tuning" class="md-nav__link">
|
|
Sysctl tuning
|
|
</a>
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
</nav>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/docker-registry/" title="Docker registry" class="md-nav__link">
|
|
Docker registry
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/grpc/" title="gRPC" class="md-nav__link">
|
|
gRPC
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/multi-tls/" title="Multi TLS certificate termination" class="md-nav__link">
|
|
Multi TLS certificate termination
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/rewrite/" title="Rewrite" class="md-nav__link">
|
|
Rewrite
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/static-ip/" title="Static IPs" class="md-nav__link">
|
|
Static IPs
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../../../examples/tls-termination/" title="TLS termination" class="md-nav__link">
|
|
TLS termination
|
|
</a>
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
</nav>
|
|
</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="#rewrite" title="Rewrite" class="md-nav__link">
|
|
Rewrite
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#session-affinity" title="Session Affinity" class="md-nav__link">
|
|
Session Affinity
|
|
</a>
|
|
|
|
<nav class="md-nav">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#cookie-affinity" title="Cookie affinity" class="md-nav__link">
|
|
Cookie affinity
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#authentication" title="Authentication" class="md-nav__link">
|
|
Authentication
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#custom-nginx-upstream-hashing" title="Custom NGINX upstream hashing" class="md-nav__link">
|
|
Custom NGINX upstream hashing
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#custom-nginx-load-balancing" title="Custom NGINX load balancing" class="md-nav__link">
|
|
Custom NGINX load balancing
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#custom-nginx-upstream-vhost" title="Custom NGINX upstream vhost" class="md-nav__link">
|
|
Custom NGINX upstream vhost
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#client-certificate-authentication" title="Client Certificate Authentication" class="md-nav__link">
|
|
Client Certificate Authentication
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#configuration-snippet" title="Configuration snippet" class="md-nav__link">
|
|
Configuration snippet
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#default-backend" title="Default Backend" class="md-nav__link">
|
|
Default Backend
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#enable-cors" title="Enable CORS" class="md-nav__link">
|
|
Enable CORS
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#server-alias" title="Server Alias" class="md-nav__link">
|
|
Server Alias
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#server-snippet" title="Server snippet" class="md-nav__link">
|
|
Server snippet
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#client-body-buffer-size" title="Client Body Buffer Size" class="md-nav__link">
|
|
Client Body Buffer Size
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#external-authentication" title="External Authentication" class="md-nav__link">
|
|
External Authentication
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#rate-limiting" title="Rate limiting" class="md-nav__link">
|
|
Rate limiting
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#permanent-redirect" title="Permanent Redirect" class="md-nav__link">
|
|
Permanent Redirect
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#permanent-redirect-code" title="Permanent Redirect Code" class="md-nav__link">
|
|
Permanent Redirect Code
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#ssl-passthrough" title="SSL Passthrough" class="md-nav__link">
|
|
SSL Passthrough
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#service-upstream" title="Service Upstream" class="md-nav__link">
|
|
Service Upstream
|
|
</a>
|
|
|
|
<nav class="md-nav">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#known-issues" title="Known Issues" class="md-nav__link">
|
|
Known Issues
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#server-side-https-enforcement-through-redirect" title="Server-side HTTPS enforcement through redirect" class="md-nav__link">
|
|
Server-side HTTPS enforcement through redirect
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#redirect-fromto-www" title="Redirect from/to www." class="md-nav__link">
|
|
Redirect from/to www.
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#whitelist-source-range" title="Whitelist source range" class="md-nav__link">
|
|
Whitelist source range
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#custom-timeouts" title="Custom timeouts" class="md-nav__link">
|
|
Custom timeouts
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#proxy-redirect" title="Proxy redirect" class="md-nav__link">
|
|
Proxy redirect
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#custom-max-body-size" title="Custom max body size" class="md-nav__link">
|
|
Custom max body size
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#proxy-cookie-domain" title="Proxy cookie domain" class="md-nav__link">
|
|
Proxy cookie domain
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#proxy-cookie-path" title="Proxy cookie path" class="md-nav__link">
|
|
Proxy cookie path
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#proxy-buffering" title="Proxy buffering" class="md-nav__link">
|
|
Proxy buffering
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#proxy-buffer-size" title="Proxy buffer size" class="md-nav__link">
|
|
Proxy buffer size
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#ssl-ciphers" title="SSL ciphers" class="md-nav__link">
|
|
SSL ciphers
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#connection-proxy-header" title="Connection proxy header" class="md-nav__link">
|
|
Connection proxy header
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#enable-access-log" title="Enable Access Log" class="md-nav__link">
|
|
Enable Access Log
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#enable-rewrite-log" title="Enable Rewrite Log" class="md-nav__link">
|
|
Enable Rewrite Log
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#lua-resty-waf" title="Lua Resty WAF" class="md-nav__link">
|
|
Lua Resty WAF
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#influxdb" title="InfluxDB" class="md-nav__link">
|
|
InfluxDB
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#backend-protocol" title="Backend Protocol" class="md-nav__link">
|
|
Backend Protocol
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#use-regex" title="Use Regex" class="md-nav__link">
|
|
Use Regex
|
|
</a>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
</ul>
|
|
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<div class="md-content">
|
|
<article class="md-content__inner md-typeset">
|
|
|
|
|
|
<a href="https://github.com/kubernetes/ingress-nginx/edit/master/docs/user-guide/nginx-configuration/annotations.md" title="Edit this page" class="md-icon md-content__icon"></a>
|
|
|
|
|
|
<h1 id="annotations">Annotations<a class="headerlink" href="#annotations" title="Permanent link">¶</a></h1>
|
|
<p>You can add these Kubernetes annotations to specific Ingress objects to customize their behavior.</p>
|
|
<div class="admonition tip">
|
|
<p class="admonition-title">Tip</p>
|
|
<p>Annotation keys and values can only be strings.
|
|
Other types, such as boolean or numeric values must be quoted,
|
|
i.e. <code class="codehilite">"true"</code>, <code class="codehilite">"false"</code>, <code class="codehilite">"100"</code>.</p>
|
|
</div>
|
|
<div class="admonition note">
|
|
<p class="admonition-title">Note</p>
|
|
<p>The annotation prefix can be changed using the
|
|
<a href="../../cli-arguments/"><code class="codehilite">--annotations-prefix</code> command line argument</a>,
|
|
but the default is <code class="codehilite">nginx.ingress.kubernetes.io</code>, as described in the
|
|
table below.</p>
|
|
</div>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>type</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><a href="#rewrite">nginx.ingress.kubernetes.io/add-base-url</a></td>
|
|
<td>"true" or "false"</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#rewrite">nginx.ingress.kubernetes.io/app-root</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#session-affinity">nginx.ingress.kubernetes.io/affinity</a></td>
|
|
<td>cookie</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#authentication">nginx.ingress.kubernetes.io/auth-realm</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#authentication">nginx.ingress.kubernetes.io/auth-secret</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#authentication">nginx.ingress.kubernetes.io/auth-type</a></td>
|
|
<td>basic or digest</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#client-certificate-authentication">nginx.ingress.kubernetes.io/auth-tls-secret</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#client-certificate-authentication">nginx.ingress.kubernetes.io/auth-tls-verify-depth</a></td>
|
|
<td>number</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#client-certificate-authentication">nginx.ingress.kubernetes.io/auth-tls-verify-client</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#client-certificate-authentication">nginx.ingress.kubernetes.io/auth-tls-error-page</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#client-certificate-authentication">nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream</a></td>
|
|
<td>"true" or "false"</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#external-authentication">nginx.ingress.kubernetes.io/auth-url</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#backend-protocol">nginx.ingress.kubernetes.io/backend-protocol</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#rewrite">nginx.ingress.kubernetes.io/base-url-scheme</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#client-body-buffer-size">nginx.ingress.kubernetes.io/client-body-buffer-size</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#configuration-snippet">nginx.ingress.kubernetes.io/configuration-snippet</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#default-backend">nginx.ingress.kubernetes.io/default-backend</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#enable-cors">nginx.ingress.kubernetes.io/enable-cors</a></td>
|
|
<td>"true" or "false"</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#enable-cors">nginx.ingress.kubernetes.io/cors-allow-origin</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#enable-cors">nginx.ingress.kubernetes.io/cors-allow-methods</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#enable-cors">nginx.ingress.kubernetes.io/cors-allow-headers</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#enable-cors">nginx.ingress.kubernetes.io/cors-allow-credentials</a></td>
|
|
<td>"true" or "false"</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#enable-cors">nginx.ingress.kubernetes.io/cors-max-age</a></td>
|
|
<td>number</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#server-side-https-enforcement-through-redirect">nginx.ingress.kubernetes.io/force-ssl-redirect</a></td>
|
|
<td>"true" or "false"</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#redirect-from-to-www">nginx.ingress.kubernetes.io/from-to-www-redirect</a></td>
|
|
<td>"true" or "false"</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#rate-limiting">nginx.ingress.kubernetes.io/limit-connections</a></td>
|
|
<td>number</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#rate-limiting">nginx.ingress.kubernetes.io/limit-rps</a></td>
|
|
<td>number</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#permanent-redirect">nginx.ingress.kubernetes.io/permanent-redirect</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#permanent-redirect-code">nginx.ingress.kubernetes.io/permanent-redirect-code</a></td>
|
|
<td>number</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#custom-max-body-size">nginx.ingress.kubernetes.io/proxy-body-size</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#proxy-cookie-domain">nginx.ingress.kubernetes.io/proxy-cookie-domain</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#proxy-cookie-path">nginx.ingress.kubernetes.io/proxy-cookie-path</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#custom-timeouts">nginx.ingress.kubernetes.io/proxy-connect-timeout</a></td>
|
|
<td>number</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#custom-timeouts">nginx.ingress.kubernetes.io/proxy-send-timeout</a></td>
|
|
<td>number</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#custom-timeouts">nginx.ingress.kubernetes.io/proxy-read-timeout</a></td>
|
|
<td>number</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#custom-timeouts">nginx.ingress.kubernetes.io/proxy-next-upstream</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#custom-timeouts">nginx.ingress.kubernetes.io/proxy-next-upstream-tries</a></td>
|
|
<td>number</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#custom-timeouts">nginx.ingress.kubernetes.io/proxy-request-buffering</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#proxy-redirect">nginx.ingress.kubernetes.io/proxy-redirect-from</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#proxy-redirect">nginx.ingress.kubernetes.io/proxy-redirect-to</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#enable-rewrite-log">nginx.ingress.kubernetes.io/enable-rewrite-log</a></td>
|
|
<td>"true" or "false"</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#rewrite">nginx.ingress.kubernetes.io/rewrite-target</a></td>
|
|
<td>URI</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#secure-backends">nginx.ingress.kubernetes.io/secure-verify-ca-secret</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#server-alias">nginx.ingress.kubernetes.io/server-alias</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#server-snippet">nginx.ingress.kubernetes.io/server-snippet</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#service-upstream">nginx.ingress.kubernetes.io/service-upstream</a></td>
|
|
<td>"true" or "false"</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#cookie-affinity">nginx.ingress.kubernetes.io/session-cookie-name</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#cookie-affinity">nginx.ingress.kubernetes.io/session-cookie-hash</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#server-side-https-enforcement-through-redirect">nginx.ingress.kubernetes.io/ssl-redirect</a></td>
|
|
<td>"true" or "false"</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#ssl-passthrough">nginx.ingress.kubernetes.io/ssl-passthrough</a></td>
|
|
<td>"true" or "false"</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#custom-nginx-upstream-hashing">nginx.ingress.kubernetes.io/upstream-hash-by</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#custom-nginx-load-balancing">nginx.ingress.kubernetes.io/load-balance</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#custom-nginx-upstream-vhost">nginx.ingress.kubernetes.io/upstream-vhost</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#whitelist-source-range">nginx.ingress.kubernetes.io/whitelist-source-range</a></td>
|
|
<td>CIDR</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#proxy-buffering">nginx.ingress.kubernetes.io/proxy-buffering</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#proxy-buffer-size">nginx.ingress.kubernetes.io/proxy-buffer-size</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#ssl-ciphers">nginx.ingress.kubernetes.io/ssl-ciphers</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#connection-proxy-header">nginx.ingress.kubernetes.io/connection-proxy-header</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#enable-access-log">nginx.ingress.kubernetes.io/enable-access-log</a></td>
|
|
<td>"true" or "false"</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#lua-resty-waf">nginx.ingress.kubernetes.io/lua-resty-waf</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#lua-resty-waf">nginx.ingress.kubernetes.io/lua-resty-waf-debug</a></td>
|
|
<td>"true" or "false"</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#lua-resty-waf">nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#lua-resty-waf">nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#influxdb">nginx.ingress.kubernetes.io/enable-influxdb</a></td>
|
|
<td>"true" or "false"</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#influxdb">nginx.ingress.kubernetes.io/influxdb-measurement</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#influxdb">nginx.ingress.kubernetes.io/influxdb-port</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#influxdb">nginx.ingress.kubernetes.io/influxdb-host</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#influxdb">nginx.ingress.kubernetes.io/influxdb-server-name</a></td>
|
|
<td>string</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#use-regex">nginx.ingress.kubernetes.io/use-regex</a></td>
|
|
<td>bool</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<h3 id="rewrite">Rewrite<a class="headerlink" href="#rewrite" title="Permanent link">¶</a></h3>
|
|
<p>In some scenarios the exposed URL in the backend service differs from the specified path in the Ingress rule. Without a rewrite any request will return 404.
|
|
Set the annotation <code class="codehilite">nginx.ingress.kubernetes.io/rewrite-target</code> to the path expected by the service.</p>
|
|
<p>If the application contains relative links it is possible to add an additional annotation <code class="codehilite">nginx.ingress.kubernetes.io/add-base-url</code> that will prepend a <a href="https://developer.mozilla.org/en/docs/Web/HTML/Element/base"><code class="codehilite">base</code> tag</a> in the header of the returned HTML from the backend.</p>
|
|
<p>If the scheme of <a href="https://developer.mozilla.org/en/docs/Web/HTML/Element/base"><code class="codehilite">base</code> tag</a> need to be specific, set the annotation <code class="codehilite">nginx.ingress.kubernetes.io/base-url-scheme</code> to the scheme such as <code class="codehilite">http</code> and <code class="codehilite">https</code>.</p>
|
|
<p>If the Application Root is exposed in a different path and needs to be redirected, set the annotation <code class="codehilite">nginx.ingress.kubernetes.io/app-root</code> to redirect requests for <code class="codehilite">/</code>.</p>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<p>Please check the <a href="../../../examples/rewrite/">rewrite</a> example.</p>
|
|
</div>
|
|
<h3 id="session-affinity">Session Affinity<a class="headerlink" href="#session-affinity" title="Permanent link">¶</a></h3>
|
|
<p>The annotation <code class="codehilite">nginx.ingress.kubernetes.io/affinity</code> enables and sets the affinity type in all Upstreams of an Ingress. This way, a request will always be directed to the same upstream server.
|
|
The only affinity type available for NGINX is <code class="codehilite">cookie</code>.</p>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<p>Please check the <a href="../../../examples/affinity/cookie/">affinity</a> example.</p>
|
|
</div>
|
|
<h4 id="cookie-affinity">Cookie affinity<a class="headerlink" href="#cookie-affinity" title="Permanent link">¶</a></h4>
|
|
<p>If you use the <code class="codehilite">cookie</code> affinity type you can also specify the name of the cookie that will be used to route the requests with the annotation <code class="codehilite">nginx.ingress.kubernetes.io/session-cookie-name</code>. The default is to create a cookie named 'INGRESSCOOKIE'.</p>
|
|
<p>In case of NGINX the annotation <code class="codehilite">nginx.ingress.kubernetes.io/session-cookie-hash</code> defines which algorithm will be used to hash the used upstream. Default value is <code class="codehilite">md5</code> and possible values are <code class="codehilite">md5</code>, <code class="codehilite">sha1</code> and <code class="codehilite">index</code>.</p>
|
|
<div class="admonition attention">
|
|
<p class="admonition-title">Attention</p>
|
|
<p>The <code class="codehilite">index</code> option is not an actual hash; an in-memory index is used instead, which has less overhead.
|
|
However, with <code class="codehilite">index</code>, matching against a changing upstream server list is inconsistent.
|
|
So, at reload, if upstream servers have changed, index values are not guaranteed to correspond to the same server as before!
|
|
<strong>Use <code class="codehilite">index</code> with caution</strong> and only if you need to!</p>
|
|
</div>
|
|
<p>In NGINX this feature is implemented by the third party module <a href="https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng">nginx-sticky-module-ng</a>. The workflow used to define which upstream server will be used is explained <a href="https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng/raw/08a395c66e425540982c00482f55034e1fee67b6/docs/sticky.pdf">here</a></p>
|
|
<h3 id="authentication">Authentication<a class="headerlink" href="#authentication" title="Permanent link">¶</a></h3>
|
|
<p>Is possible to add authentication adding additional annotations in the Ingress rule. The source of the authentication is a secret that contains usernames and passwords inside the key <code class="codehilite">auth</code>.</p>
|
|
<p>The annotations are:
|
|
<div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-type: [basic|digest]
|
|
</pre></div></p>
|
|
<p>Indicates the <a href="https://tools.ietf.org/html/rfc2617">HTTP Authentication Type: Basic or Digest Access Authentication</a>.</p>
|
|
<div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-secret: secretName
|
|
</pre></div>
|
|
|
|
<p>The name of the Secret that contains the usernames and passwords which are granted access to the <code class="codehilite">path</code>s defined in the Ingress rules.
|
|
This annotation also accepts the alternative form "namespace/secretName", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.</p>
|
|
<div class="codehilite"><pre><span></span>nginx.ingress.kubernetes.io/auth-realm: "realm string"
|
|
</pre></div>
|
|
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<p>Please check the <a href="../../../examples/auth/basic/">auth</a> example.</p>
|
|
</div>
|
|
<h3 id="custom-nginx-upstream-hashing">Custom NGINX upstream hashing<a class="headerlink" href="#custom-nginx-upstream-hashing" title="Permanent link">¶</a></h3>
|
|
<p>NGINX supports load balancing by client-server mapping based on <a href="http://nginx.org/en/docs/http/ngx_http_upstream_module.html#hash">consistent hashing</a> for a given key. The key can contain text, variables or any combination thereof. This feature allows for request stickiness other than client IP or cookies. The <a href="http://www.last.fm/user/RJ/journal/2007/04/10/392555/">ketama</a> consistent hashing method will be used which ensures only a few keys would be remapped to different servers on upstream group changes.</p>
|
|
<p>To enable consistent hashing for a backend:</p>
|
|
<p><code class="codehilite">nginx.ingress.kubernetes.io/upstream-hash-by</code>: the nginx variable, text value or any combination thereof to use for consistent hashing. For example <code class="codehilite">nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"</code> to consistently hash upstream requests by the current request URI.</p>
|
|
<h3 id="custom-nginx-load-balancing">Custom NGINX load balancing<a class="headerlink" href="#custom-nginx-load-balancing" title="Permanent link">¶</a></h3>
|
|
<p>This is similar to (https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/nginx-configuration/configmap.md#load-balance) but configures load balancing algorithm per ingress.</p>
|
|
<blockquote>
|
|
<p>Note that <code class="codehilite">nginx.ingress.kubernetes.io/upstream-hash-by</code> takes preference over this. If this and <code class="codehilite">nginx.ingress.kubernetes.io/upstream-hash-by</code> are not set then we fallback to using globally configured load balancing algorithm.</p>
|
|
</blockquote>
|
|
<h3 id="custom-nginx-upstream-vhost">Custom NGINX upstream vhost<a class="headerlink" href="#custom-nginx-upstream-vhost" title="Permanent link">¶</a></h3>
|
|
<p>This configuration setting allows you to control the value for host in the following statement: <code class="codehilite">proxy_set_header Host $host</code>, which forms part of the location block. This is useful if you need to call the upstream server by something other than <code class="codehilite">$host</code>.</p>
|
|
<h3 id="client-certificate-authentication">Client Certificate Authentication<a class="headerlink" href="#client-certificate-authentication" title="Permanent link">¶</a></h3>
|
|
<p>It is possible to enable Client Certificate Authentication using additional annotations in Ingress Rule.</p>
|
|
<p>The annotations are:</p>
|
|
<ul>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/auth-tls-secret: secretName</code>:
|
|
The name of the Secret that contains the full Certificate Authority chain <code class="codehilite">ca.crt</code> that is enabled to authenticate against this Ingress.
|
|
This annotation also accepts the alternative form "namespace/secretName", in which case the Secret lookup is performed in the referenced namespace instead of the Ingress namespace.</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/auth-tls-verify-depth</code>:
|
|
The validation depth between the provided client certificate and the Certification Authority chain.</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/auth-tls-verify-client</code>:
|
|
Enables verification of client certificates.</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/auth-tls-error-page</code>:
|
|
The URL/Page that user should be redirected in case of a Certificate Authentication Error</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream</code>:
|
|
Indicates if the received certificates should be passed or not to the upstream server. By default this is disabled.</li>
|
|
</ul>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<p>Please check the <a href="../../../examples/auth/client-certs/">client-certs</a> example.</p>
|
|
</div>
|
|
<div class="admonition attention">
|
|
<p class="admonition-title">Attention</p>
|
|
<p>TLS with Client Authentication is <strong>not</strong> possible in Cloudflare and might result in unexpected behavior.</p>
|
|
<p>Cloudflare only allows Authenticated Origin Pulls and is required to use their own certificate: <a href="https://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/">https://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/</a></p>
|
|
<p>Only Authenticated Origin Pulls are allowed and can be configured by following their tutorial: <a href="https://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls">https://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls</a></p>
|
|
</div>
|
|
<h3 id="configuration-snippet">Configuration snippet<a class="headerlink" href="#configuration-snippet" title="Permanent link">¶</a></h3>
|
|
<p>Using this annotation you can add additional configuration to the NGINX location. For example:</p>
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/configuration-snippet</span><span class="p p-Indicator">:</span> <span class="p p-Indicator">|</span>
|
|
<span class="no">more_set_headers "Request-Id: $req_id";</span>
|
|
</pre></div>
|
|
|
|
<h3 id="default-backend">Default Backend<a class="headerlink" href="#default-backend" title="Permanent link">¶</a></h3>
|
|
<p>The ingress controller requires a <a href="../../default-backend/">default backend</a>.
|
|
This service handles the response when the service in the Ingress rule does not have endpoints.
|
|
This is a global configuration for the ingress controller. In some cases could be required to return a custom content or format. In this scenario we can use the annotation <code class="codehilite">nginx.ingress.kubernetes.io/default-backend: <svc name></code> to specify a custom default backend.</p>
|
|
<h3 id="enable-cors">Enable CORS<a class="headerlink" href="#enable-cors" title="Permanent link">¶</a></h3>
|
|
<p>To enable Cross-Origin Resource Sharing (CORS) in an Ingress rule, add the annotation
|
|
<code class="codehilite">nginx.ingress.kubernetes.io/enable-cors: "true"</code>. This will add a section in the server
|
|
location enabling this functionality.</p>
|
|
<p>CORS can be controlled with the following annotations:</p>
|
|
<ul>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/cors-allow-methods</code>
|
|
controls which methods are accepted. This is a multi-valued field, separated by ',' and
|
|
accepts only letters (upper and lower case).</li>
|
|
<li>Default: <code class="codehilite">GET, PUT, POST, DELETE, PATCH, OPTIONS</code></li>
|
|
<li>
|
|
<p>Example: <code class="codehilite">nginx.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code class="codehilite">nginx.ingress.kubernetes.io/cors-allow-headers</code>
|
|
controls which headers are accepted. This is a multi-valued field, separated by ',' and accepts letters,
|
|
numbers, _ and -.</p>
|
|
</li>
|
|
<li>Default: <code class="codehilite">DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization</code></li>
|
|
<li>
|
|
<p>Example: <code class="codehilite">nginx.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For, X-app123-XPTO"</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code class="codehilite">nginx.ingress.kubernetes.io/cors-allow-origin</code>
|
|
controls what's the accepted Origin for CORS.
|
|
This is a single field value, with the following format: <code class="codehilite">http(s)://origin-site.com</code> or <code class="codehilite">http(s)://origin-site.com:port</code></p>
|
|
</li>
|
|
<li>Default: <code class="codehilite">*</code></li>
|
|
<li>
|
|
<p>Example: <code class="codehilite">nginx.ingress.kubernetes.io/cors-allow-origin: "https://origin-site.com:4443"</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code class="codehilite">nginx.ingress.kubernetes.io/cors-allow-credentials</code>
|
|
controls if credentials can be passed during CORS operations.</p>
|
|
</li>
|
|
<li>Default: <code class="codehilite">true</code></li>
|
|
<li>
|
|
<p>Example: <code class="codehilite">nginx.ingress.kubernetes.io/cors-allow-credentials: "false"</code></p>
|
|
</li>
|
|
<li>
|
|
<p><code class="codehilite">nginx.ingress.kubernetes.io/cors-max-age</code>
|
|
controls how long preflight requests can be cached.
|
|
Default: <code class="codehilite">1728000</code>
|
|
Example: <code class="codehilite">nginx.ingress.kubernetes.io/cors-max-age: 600</code></p>
|
|
</li>
|
|
</ul>
|
|
<div class="admonition note">
|
|
<p class="admonition-title">Note</p>
|
|
<p>For more information please see <a href="https://enable-cors.org/server_nginx.html">https://enable-cors.org</a> </p>
|
|
</div>
|
|
<h3 id="server-alias">Server Alias<a class="headerlink" href="#server-alias" title="Permanent link">¶</a></h3>
|
|
<p>To add Server Aliases to an Ingress rule add the annotation <code class="codehilite">nginx.ingress.kubernetes.io/server-alias: "<alias>"</code>.
|
|
This will create a server with the same configuration, but a different <code class="codehilite">server_name</code> as the provided host.</p>
|
|
<div class="admonition note">
|
|
<p class="admonition-title">Note</p>
|
|
<p>A server-alias name cannot conflict with the hostname of an existing server. If it does the server-alias annotation will be ignored.
|
|
If a server-alias is created and later a new server with the same hostname is created,
|
|
the new server configuration will take place over the alias configuration.</p>
|
|
</div>
|
|
<p>For more information please see <a href="http://nginx.org/en/docs/http/ngx_http_core_module.html#server_name">the <code class="codehilite">server_name</code> documentation</a>.</p>
|
|
<h3 id="server-snippet">Server snippet<a class="headerlink" href="#server-snippet" title="Permanent link">¶</a></h3>
|
|
<p>Using the annotation <code class="codehilite">nginx.ingress.kubernetes.io/server-snippet</code> it is possible to add custom configuration in the server configuration block.</p>
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">apiVersion</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">extensions/v1beta1</span>
|
|
<span class="l l-Scalar l-Scalar-Plain">kind</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">Ingress</span>
|
|
<span class="l l-Scalar l-Scalar-Plain">metadata</span><span class="p p-Indicator">:</span>
|
|
<span class="l l-Scalar l-Scalar-Plain">annotations</span><span class="p p-Indicator">:</span>
|
|
<span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/server-snippet</span><span class="p p-Indicator">:</span> <span class="p p-Indicator">|</span>
|
|
<span class="no">set $agentflag 0;</span>
|
|
|
|
<span class="no">if ($http_user_agent ~* "(Mobile)" ){</span>
|
|
<span class="no">set $agentflag 1;</span>
|
|
<span class="no">}</span>
|
|
|
|
<span class="no">if ( $agentflag = 1 ) {</span>
|
|
<span class="no">return 301 https://m.example.com;</span>
|
|
<span class="no">}</span>
|
|
</pre></div>
|
|
|
|
<div class="admonition attention">
|
|
<p class="admonition-title">Attention</p>
|
|
<p>This annotation can be used only once per host.</p>
|
|
</div>
|
|
<h3 id="client-body-buffer-size">Client Body Buffer Size<a class="headerlink" href="#client-body-buffer-size" title="Permanent link">¶</a></h3>
|
|
<p>Sets buffer size for reading client request body per location. In case the request body is larger than the buffer,
|
|
the whole body or only its part is written to a temporary file. By default, buffer size is equal to two memory pages.
|
|
This is 8K on x86, other 32-bit platforms, and x86-64. It is usually 16K on other 64-bit platforms. This annotation is
|
|
applied to each location provided in the ingress rule.</p>
|
|
<div class="admonition note">
|
|
<p class="admonition-title">Note</p>
|
|
<p>The annotation value must be given in a format understood by Nginx.</p>
|
|
</div>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<ul>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/client-body-buffer-size: "1000"</code> # 1000 bytes</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/client-body-buffer-size: 1k</code> # 1 kilobyte</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/client-body-buffer-size: 1K</code> # 1 kilobyte</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/client-body-buffer-size: 1m</code> # 1 megabyte</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/client-body-buffer-size: 1M</code> # 1 megabyte</li>
|
|
</ul>
|
|
</div>
|
|
<p>For more information please see <a href="http://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size">http://nginx.org</a></p>
|
|
<h3 id="external-authentication">External Authentication<a class="headerlink" href="#external-authentication" title="Permanent link">¶</a></h3>
|
|
<p>To use an existing service that provides authentication the Ingress rule can be annotated with <code class="codehilite">nginx.ingress.kubernetes.io/auth-url</code> to indicate the URL where the HTTP request should be sent.</p>
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/auth-url</span><span class="p p-Indicator">:</span> <span class="s">"URL</span><span class="nv"> </span><span class="s">to</span><span class="nv"> </span><span class="s">the</span><span class="nv"> </span><span class="s">authentication</span><span class="nv"> </span><span class="s">service"</span>
|
|
</pre></div>
|
|
|
|
<p>Additionally it is possible to set:</p>
|
|
<ul>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/auth-method</code>:
|
|
<code class="codehilite"><Method></code> to specify the HTTP method to use.</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/auth-signin</code>:
|
|
<code class="codehilite"><SignIn_URL></code> to specify the location of the error page.</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/auth-response-headers</code>:
|
|
<code class="codehilite"><Response_Header_1, ..., Response_Header_n></code> to specify headers to pass to backend once authentication request completes.</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/auth-request-redirect</code>:
|
|
<code class="codehilite"><Request_Redirect_URL></code> to specify the X-Auth-Request-Redirect header value.</li>
|
|
</ul>
|
|
<div class="admonition example">
|
|
<p class="admonition-title">Example</p>
|
|
<p>Please check the <a href="../../../examples/auth/external-auth/">external-auth</a> example.</p>
|
|
</div>
|
|
<h3 id="rate-limiting">Rate limiting<a class="headerlink" href="#rate-limiting" title="Permanent link">¶</a></h3>
|
|
<p>These annotations define a limit on the connections that can be opened by a single client IP address.
|
|
This can be used to mitigate <a href="https://www.nginx.com/blog/mitigating-ddos-attacks-with-nginx-and-nginx-plus">DDoS Attacks</a>.</p>
|
|
<ul>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/limit-connections</code>: number of concurrent connections allowed from a single IP address.</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/limit-rps</code>: number of connections that may be accepted from a given IP each second.</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/limit-rpm</code>: number of connections that may be accepted from a given IP each minute.</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/limit-rate-after</code>: sets the initial amount after which the further transmission of a response to a client will be rate limited.</li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/limit-rate</code>: rate of request that accepted from a client each second.</li>
|
|
</ul>
|
|
<p>You can specify the client IP source ranges to be excluded from rate-limiting through the <code class="codehilite">nginx.ingress.kubernetes.io/limit-whitelist</code> annotation. The value is a comma separated list of CIDRs.</p>
|
|
<p>If you specify multiple annotations in a single Ingress rule, <code class="codehilite">limit-rpm</code>, and then <code class="codehilite">limit-rps</code> takes precedence.</p>
|
|
<p>The annotation <code class="codehilite">nginx.ingress.kubernetes.io/limit-rate</code>, <code class="codehilite">nginx.ingress.kubernetes.io/limit-rate-after</code> define a limit the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.</p>
|
|
<p>To configure this setting globally for all Ingress rules, the <code class="codehilite">limit-rate-after</code> and <code class="codehilite">limit-rate</code> value may be set in the <a href="../configmap/">NGINX ConfigMap</a>. if you set the value in ingress annotation will cover global setting.</p>
|
|
<h3 id="permanent-redirect">Permanent Redirect<a class="headerlink" href="#permanent-redirect" title="Permanent link">¶</a></h3>
|
|
<p>This annotation allows to return a permanent redirect instead of sending data to the upstream. For example <code class="codehilite">nginx.ingress.kubernetes.io/permanent-redirect: https://www.google.com</code> would redirect everything to Google.</p>
|
|
<h3 id="permanent-redirect-code">Permanent Redirect Code<a class="headerlink" href="#permanent-redirect-code" title="Permanent link">¶</a></h3>
|
|
<p>This annotation allows you to modify the status code used for permanent redirects. For example <code class="codehilite">nginx.ingress.kubernetes.io/permanent-redirect-code: '308'</code> would return your permanent-redirect with a 308.</p>
|
|
<h3 id="ssl-passthrough">SSL Passthrough<a class="headerlink" href="#ssl-passthrough" title="Permanent link">¶</a></h3>
|
|
<p>The annotation <code class="codehilite">nginx.ingress.kubernetes.io/ssl-passthrough</code> instructs the controller to send TLS connections directly
|
|
to the backend instead of letting NGINX decrypt the communication. See also <a href="../tls/#ssl-passthrough">TLS/HTTPS</a> in
|
|
the User guide.</p>
|
|
<div class="admonition note">
|
|
<p class="admonition-title">Note</p>
|
|
<p>SSL Passthrough is <strong>disabled by default</strong> and requires starting the controller with the
|
|
<a href="../cli-arguments/"><code class="codehilite">--enable-ssl-passthrough</code></a> flag.</p>
|
|
</div>
|
|
<div class="admonition attention">
|
|
<p class="admonition-title">Attention</p>
|
|
<p>Because SSL Passthrough works on layer 4 of the OSI model (TCP) and not on the layer 7 (HTTP), using SSL Passthrough
|
|
invalidates all the other annotations set on an Ingress object.</p>
|
|
</div>
|
|
<h3 id="service-upstream">Service Upstream<a class="headerlink" href="#service-upstream" title="Permanent link">¶</a></h3>
|
|
<p>By default the NGINX ingress controller uses a list of all endpoints (Pod IP/port) in the NGINX upstream configuration.</p>
|
|
<p>The <code class="codehilite">nginx.ingress.kubernetes.io/service-upstream</code> annotation disables that behavior and instead uses a single upstream in NGINX, the service's Cluster IP and port.</p>
|
|
<p>This can be desirable for things like zero-downtime deployments as it reduces the need to reload NGINX configuration when Pods come up and down. See issue <a href="https://github.com/kubernetes/ingress-nginx/issues/257">#257</a>.</p>
|
|
<h4 id="known-issues">Known Issues<a class="headerlink" href="#known-issues" title="Permanent link">¶</a></h4>
|
|
<p>If the <code class="codehilite">service-upstream</code> annotation is specified the following things should be taken into consideration:</p>
|
|
<ul>
|
|
<li>Sticky Sessions will not work as only round-robin load balancing is supported.</li>
|
|
<li>The <code class="codehilite">proxy_next_upstream</code> directive will not have any effect meaning on error the request will not be dispatched to another upstream.</li>
|
|
</ul>
|
|
<h3 id="server-side-https-enforcement-through-redirect">Server-side HTTPS enforcement through redirect<a class="headerlink" href="#server-side-https-enforcement-through-redirect" title="Permanent link">¶</a></h3>
|
|
<p>By default the controller redirects (308) to HTTPS if TLS is enabled for that ingress.
|
|
If you want to disable this behavior globally, you can use <code class="codehilite">ssl-redirect: "false"</code> in the NGINX <a href="../configmap/">config map</a>.</p>
|
|
<p>To configure this feature for specific ingress resources, you can use the <code class="codehilite">nginx.ingress.kubernetes.io/ssl-redirect: "false"</code>
|
|
annotation in the particular resource.</p>
|
|
<p>When using SSL offloading outside of cluster (e.g. AWS ELB) it may be useful to enforce a redirect to HTTPS
|
|
even when there is no TLS certificate available.
|
|
This can be achieved by using the <code class="codehilite">nginx.ingress.kubernetes.io/force-ssl-redirect: "true"</code> annotation in the particular resource.</p>
|
|
<h3 id="redirect-fromto-www">Redirect from/to www.<a class="headerlink" href="#redirect-fromto-www" title="Permanent link">¶</a></h3>
|
|
<p>In some scenarios is required to redirect from <code class="codehilite">www.domain.com</code> to <code class="codehilite">domain.com</code> or vice versa.
|
|
To enable this feature use the annotation <code class="codehilite">nginx.ingress.kubernetes.io/from-to-www-redirect: "true"</code></p>
|
|
<div class="admonition attention">
|
|
<p class="admonition-title">Attention</p>
|
|
<p>If at some point a new Ingress is created with a host equal to one of the options (like <code class="codehilite">domain.com</code>) the annotation will be omitted.</p>
|
|
</div>
|
|
<h3 id="whitelist-source-range">Whitelist source range<a class="headerlink" href="#whitelist-source-range" title="Permanent link">¶</a></h3>
|
|
<p>You can specify allowed client IP source ranges through the <code class="codehilite">nginx.ingress.kubernetes.io/whitelist-source-range</code> annotation.
|
|
The value is a comma separated list of <a href="https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing">CIDRs</a>, e.g. <code class="codehilite">10.0.0.0/24,172.10.0.1</code>.</p>
|
|
<p>To configure this setting globally for all Ingress rules, the <code class="codehilite">whitelist-source-range</code> value may be set in the <a href="../configmap/">NGINX ConfigMap</a>.</p>
|
|
<div class="admonition note">
|
|
<p class="admonition-title">Note</p>
|
|
<p>Adding an annotation to an Ingress rule overrides any global restriction.</p>
|
|
</div>
|
|
<h3 id="custom-timeouts">Custom timeouts<a class="headerlink" href="#custom-timeouts" title="Permanent link">¶</a></h3>
|
|
<p>Using the configuration configmap it is possible to set the default global timeout for connections to the upstream servers.
|
|
In some scenarios is required to have different values. To allow this we provide annotations that allows this customization:</p>
|
|
<ul>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/proxy-connect-timeout</code></li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/proxy-send-timeout</code></li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/proxy-read-timeout</code></li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/proxy-next-upstream</code></li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/proxy-next-upstream-tries</code></li>
|
|
<li><code class="codehilite">nginx.ingress.kubernetes.io/proxy-request-buffering</code></li>
|
|
</ul>
|
|
<h3 id="proxy-redirect">Proxy redirect<a class="headerlink" href="#proxy-redirect" title="Permanent link">¶</a></h3>
|
|
<p>With the annotations <code class="codehilite">nginx.ingress.kubernetes.io/proxy-redirect-from</code> and <code class="codehilite">nginx.ingress.kubernetes.io/proxy-redirect-to</code> it is possible to
|
|
set the text that should be changed in the <code class="codehilite">Location</code> and <code class="codehilite">Refresh</code> header fields of a proxied server response (http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect)</p>
|
|
<p>Setting "off" or "default" in the annotation <code class="codehilite">nginx.ingress.kubernetes.io/proxy-redirect-from</code> disables <code class="codehilite">nginx.ingress.kubernetes.io/proxy-redirect-to</code>,
|
|
otherwise, both annotations must be used in unison. Note that each annotation must be a string without spaces.</p>
|
|
<p>By default the value of each annotation is "off".</p>
|
|
<h3 id="custom-max-body-size">Custom max body size<a class="headerlink" href="#custom-max-body-size" title="Permanent link">¶</a></h3>
|
|
<p>For NGINX, an 413 error will be returned to the client when the size in a request exceeds the maximum allowed size of the client request body. This size can be configured by the parameter <a href="http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size"><code class="codehilite">client_max_body_size</code></a>.</p>
|
|
<p>To configure this setting globally for all Ingress rules, the <code class="codehilite">proxy-body-size</code> value may be set in the <a href="../configmap/">NGINX ConfigMap</a>.
|
|
To use custom values in an Ingress rule define these annotation:</p>
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-body-size</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">8m</span>
|
|
</pre></div>
|
|
|
|
<h3 id="proxy-cookie-domain">Proxy cookie domain<a class="headerlink" href="#proxy-cookie-domain" title="Permanent link">¶</a></h3>
|
|
<p>Sets a text that <a href="http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_domain">should be changed in the domain attribute</a> of the "Set-Cookie" header fields of a proxied server response.</p>
|
|
<p>To configure this setting globally for all Ingress rules, the <code class="codehilite">proxy-cookie-domain</code> value may be set in the <a href="../configmap/">NGINX ConfigMap</a>.</p>
|
|
<h3 id="proxy-cookie-path">Proxy cookie path<a class="headerlink" href="#proxy-cookie-path" title="Permanent link">¶</a></h3>
|
|
<p>Sets a text that <a href="http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cookie_path">should be changed in the path attribute</a> of the "Set-Cookie" header fields of a proxied server response.</p>
|
|
<p>To configure this setting globally for all Ingress rules, the <code class="codehilite">proxy-cookie-path</code> value may be set in the <a href="../configmap/">NGINX ConfigMap</a>.</p>
|
|
<h3 id="proxy-buffering">Proxy buffering<a class="headerlink" href="#proxy-buffering" title="Permanent link">¶</a></h3>
|
|
<p>Enable or disable proxy buffering <a href="http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering"><code class="codehilite">proxy_buffering</code></a>.
|
|
By default proxy buffering is disabled in the NGINX config.</p>
|
|
<p>To configure this setting globally for all Ingress rules, the <code class="codehilite">proxy-buffering</code> value may be set in the <a href="../configmap/">NGINX ConfigMap</a>.
|
|
To use custom values in an Ingress rule define these annotation:</p>
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-buffering</span><span class="p p-Indicator">:</span> <span class="s">"on"</span>
|
|
</pre></div>
|
|
|
|
<h3 id="proxy-buffer-size">Proxy buffer size<a class="headerlink" href="#proxy-buffer-size" title="Permanent link">¶</a></h3>
|
|
<p>Sets the size of the buffer <a href="http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size"><code class="codehilite">proxy_buffer_size</code></a> used for reading the first part of the response received from the proxied server.
|
|
By default proxy buffer size is set as "4k"</p>
|
|
<p>To configure this setting globally, set <code class="codehilite">proxy-buffer-size</code> in <a href="../configmap/">NGINX ConfigMap</a>. To use custom values in an Ingress rule, define this annotation:
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/proxy-buffer-size</span><span class="p p-Indicator">:</span> <span class="s">"8k"</span>
|
|
</pre></div></p>
|
|
<h3 id="ssl-ciphers">SSL ciphers<a class="headerlink" href="#ssl-ciphers" title="Permanent link">¶</a></h3>
|
|
<p>Specifies the <a href="http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers">enabled ciphers</a>.</p>
|
|
<p>Using this annotation will set the <code class="codehilite">ssl_ciphers</code> directive at the server level. This configuration is active for all the paths in the host.</p>
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/ssl-ciphers</span><span class="p p-Indicator">:</span> <span class="s">"ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP"</span>
|
|
</pre></div>
|
|
|
|
<h3 id="connection-proxy-header">Connection proxy header<a class="headerlink" href="#connection-proxy-header" title="Permanent link">¶</a></h3>
|
|
<p>Using this annotation will override the default connection header set by NGINX.
|
|
To use custom values in an Ingress rule, define the annotation:</p>
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/connection-proxy-header</span><span class="p p-Indicator">:</span> <span class="s">"keep-alive"</span>
|
|
</pre></div>
|
|
|
|
<h3 id="enable-access-log">Enable Access Log<a class="headerlink" href="#enable-access-log" title="Permanent link">¶</a></h3>
|
|
<p>Access logs are enabled by default, but in some scenarios access logs might be required to be disabled for a given
|
|
ingress. To do this, use the annotation:</p>
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-access-log</span><span class="p p-Indicator">:</span> <span class="s">"false"</span>
|
|
</pre></div>
|
|
|
|
<h3 id="enable-rewrite-log">Enable Rewrite Log<a class="headerlink" href="#enable-rewrite-log" title="Permanent link">¶</a></h3>
|
|
<p>Rewrite logs are not enabled by default. In some scenarios it could be required to enable NGINX rewrite logs.
|
|
Note that rewrite logs are sent to the error_log file at the notice level. To enable this feature use the annotation:</p>
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-rewrite-log</span><span class="p p-Indicator">:</span> <span class="s">"true"</span>
|
|
</pre></div>
|
|
|
|
<h3 id="lua-resty-waf">Lua Resty WAF<a class="headerlink" href="#lua-resty-waf" title="Permanent link">¶</a></h3>
|
|
<p>Using <code class="codehilite">lua-resty-waf-*</code> annotations we can enable and control the <a href="https://github.com/p0pr0ck5/lua-resty-waf">lua-resty-waf</a>
|
|
Web Application Firewall per location.</p>
|
|
<p>Following configuration will enable the WAF for the paths defined in the corresponding ingress:</p>
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf</span><span class="p p-Indicator">:</span> <span class="s">"active"</span>
|
|
</pre></div>
|
|
|
|
<p>In order to run it in debugging mode you can set <code class="codehilite">nginx.ingress.kubernetes.io/lua-resty-waf-debug</code> to <code class="codehilite">"true"</code> in addition to the above configuration.
|
|
The other possible values for <code class="codehilite">nginx.ingress.kubernetes.io/lua-resty-waf</code> are <code class="codehilite">inactive</code> and <code class="codehilite">simulate</code>.
|
|
In <code class="codehilite">inactive</code> mode WAF won't do anything, whereas in <code class="codehilite">simulate</code> mode it will log a warning message if there's a matching WAF rule for given request. This is useful to debug a rule and eliminate possible false positives before fully deploying it.</p>
|
|
<p><code class="codehilite">lua-resty-waf</code> comes with predefined set of rules <a href="https://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules">https://github.com/p0pr0ck5/lua-resty-waf/tree/84b4f40362500dd0cb98b9e71b5875cb1a40f1ad/rules</a> that covers ModSecurity CRS.
|
|
You can use <code class="codehilite">nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets</code> to ignore a subset of those rulesets. For an example:</p>
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets</span><span class="p p-Indicator">:</span> <span class="s">"41000_sqli,</span><span class="nv"> </span><span class="s">42000_xss"</span>
|
|
</pre></div>
|
|
|
|
<p>will ignore the two mentioned rulesets.</p>
|
|
<p>It is also possible to configure custom WAF rules per ingress using the <code class="codehilite">nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules</code> annotation. For an example the following snippet will configure a WAF rule to deny requests with query string value that contains word <code class="codehilite">foo</code>:</p>
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules</span><span class="p p-Indicator">:</span> <span class="s">'[=[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">"access":</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">"actions":</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">"disrupt"</span><span class="nv"> </span><span class="s">:</span><span class="nv"> </span><span class="s">"DENY"</span><span class="nv"> </span><span class="s">},</span><span class="nv"> </span><span class="s">"id":</span><span class="nv"> </span><span class="s">10001,</span><span class="nv"> </span><span class="s">"msg":</span><span class="nv"> </span><span class="s">"my</span><span class="nv"> </span><span class="s">custom</span><span class="nv"> </span><span class="s">rule",</span><span class="nv"> </span><span class="s">"operator":</span><span class="nv"> </span><span class="s">"STR_CONTAINS",</span><span class="nv"> </span><span class="s">"pattern":</span><span class="nv"> </span><span class="s">"foo",</span><span class="nv"> </span><span class="s">"vars":</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">{</span><span class="nv"> </span><span class="s">"parse":</span><span class="nv"> </span><span class="s">[</span><span class="nv"> </span><span class="s">"values",</span><span class="nv"> </span><span class="s">1</span><span class="nv"> </span><span class="s">],</span><span class="nv"> </span><span class="s">"type":</span><span class="nv"> </span><span class="s">"REQUEST_ARGS"</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">]</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">],</span><span class="nv"> </span><span class="s">"body_filter":</span><span class="nv"> </span><span class="s">[],</span><span class="nv"> </span><span class="s">"header_filter":[]</span><span class="nv"> </span><span class="s">}</span><span class="nv"> </span><span class="s">]=]'</span>
|
|
</pre></div>
|
|
|
|
<p>For details on how to write WAF rules, please refer to <a href="https://github.com/p0pr0ck5/lua-resty-waf">https://github.com/p0pr0ck5/lua-resty-waf</a>.</p>
|
|
<h3 id="influxdb">InfluxDB<a class="headerlink" href="#influxdb" title="Permanent link">¶</a></h3>
|
|
<p>Using <code class="codehilite">influxdb-*</code> annotations we can monitor requests passing through a Location by sending them to an InfluxDB backend exposing the UDP socket
|
|
using the <a href="https://github.com/influxdata/nginx-influxdb-module/">nginx-influxdb-module</a>.</p>
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/enable-influxdb</span><span class="p p-Indicator">:</span> <span class="s">"true"</span>
|
|
<span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/influxdb-measurement</span><span class="p p-Indicator">:</span> <span class="s">"nginx-reqs"</span>
|
|
<span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/influxdb-port</span><span class="p p-Indicator">:</span> <span class="s">"8089"</span>
|
|
<span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/influxdb-host</span><span class="p p-Indicator">:</span> <span class="s">"127.0.0.1"</span>
|
|
<span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/influxdb-server-name</span><span class="p p-Indicator">:</span> <span class="s">"nginx-ingress"</span>
|
|
</pre></div>
|
|
|
|
<p>For the <code class="codehilite">influxdb-host</code> parameter you have two options:</p>
|
|
<ul>
|
|
<li>Use an InfluxDB server configured with the <a href="https://docs.influxdata.com/influxdb/v1.5/supported_protocols/udp/">UDP protocol</a> enabled. </li>
|
|
<li>Deploy Telegraf as a sidecar proxy to the Ingress controller configured to listen UDP with the <a href="https://github.com/influxdata/telegraf/tree/release-1.6/plugins/inputs/socket_listener">socket listener input</a> and to write using
|
|
anyone of the <a href="https://github.com/influxdata/telegraf/tree/release-1.7/plugins/outputs">outputs plugins</a> like InfluxDB, Apache Kafka,
|
|
Prometheus, etc.. (recommended)</li>
|
|
</ul>
|
|
<p>It's important to remember that there's no DNS resolver at this stage so you will have to configure
|
|
an ip address to <code class="codehilite">nginx.ingress.kubernetes.io/influxdb-host</code>. If you deploy Influx or Telegraf as sidecar (another container in the same pod) this becomes straightforward since you can directly use <code class="codehilite">127.0.0.1</code>.</p>
|
|
<h3 id="backend-protocol">Backend Protocol<a class="headerlink" href="#backend-protocol" title="Permanent link">¶</a></h3>
|
|
<p>Using <code class="codehilite">backend-protocol</code> annotations is possible to indicate how NGINX should communicate with the backend service.
|
|
Valid Values: HTTP, HTTPS, GRPC, GRPCS and AJP</p>
|
|
<p>By default NGINX uses <code class="codehilite">HTTP</code>.</p>
|
|
<p>Example:</p>
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/backend-protocol</span><span class="p p-Indicator">:</span> <span class="s">"HTTPS"</span>
|
|
</pre></div>
|
|
|
|
<h3 id="use-regex">Use Regex<a class="headerlink" href="#use-regex" title="Permanent link">¶</a></h3>
|
|
<p>Using the <code class="codehilite">nginx.ingress.kubernetes.io/use-regex</code> annotation will indicate whether or not the paths defined on an Ingress use regular expressions. The default value is <code class="codehilite">false</code>.</p>
|
|
<p>The following will indicate that regular expression paths are being used:
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/use-regex</span><span class="p p-Indicator">:</span> <span class="s">"true"</span>
|
|
</pre></div></p>
|
|
<p>The following will indicate that regular expression paths are <strong>not</strong> being used:
|
|
<div class="codehilite"><pre><span></span><span class="l l-Scalar l-Scalar-Plain">nginx.ingress.kubernetes.io/use-regex</span><span class="p p-Indicator">:</span> <span class="s">"false"</span>
|
|
</pre></div></p>
|
|
<p>When this annotation is set to <code class="codehilite">true</code>, the case insensitive regular expression <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#location">location modifier</a> will be enforced on ALL paths for a given host regardless of what Ingress they are defined on.</p>
|
|
<p>Additionally, if the <a href="#rewrite"><code class="codehilite">rewrite-target</code> annotation</a> is used on any Ingress for a given host, then the case insensitive regular expression <a href="https://nginx.org/en/docs/http/ngx_http_core_module.html#location">location modifier</a> will be enforced on ALL paths for a given host regardless of what Ingress they are defined on. </p>
|
|
<p>Please read about <a href="../../ingress-path-matching/">ingress path matching</a> before using this modifier. </p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</article>
|
|
</div>
|
|
</div>
|
|
</main>
|
|
|
|
|
|
<footer class="md-footer">
|
|
|
|
<div class="md-footer-nav">
|
|
<nav class="md-footer-nav__inner md-grid">
|
|
|
|
<a href="../" 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="../configmap/" title="ConfigMap" 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>
|
|
ConfigMap
|
|
</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.583bbe55.js"></script>
|
|
|
|
<script>app.initialize({version:"1.0.4",url:{base:"../../.."}})</script>
|
|
|
|
|
|
|
|
|
|
<script>!function(e,a,t,n,o,c,i){e.GoogleAnalyticsObject=o,e.ga=e.ga||function(){(e.ga.q=e.ga.q||[]).push(arguments)},e.ga.l=1*new Date,c=a.createElement(t),i=a.getElementsByTagName(t)[0],c.async=1,c.src="https://www.google-analytics.com/analytics.js",i.parentNode.insertBefore(c,i)}(window,document,"script",0,"ga"),ga("create","UA-118407822-1","kubernetes.github.io"),ga("set","anonymizeIp",!0),ga("send","pageview");var links=document.getElementsByTagName("a");if(Array.prototype.map.call(links,function(e){e.host!=document.location.host&&e.addEventListener("click",function(){var a=e.getAttribute("data-md-action")||"follow";ga("send","event","outbound",a,e.href)})}),document.forms.search){var query=document.forms.search.query;query.addEventListener("blur",function(){if(this.value){var e=document.location.pathname;ga("send","pageview",e+"?q="+this.value)}})}</script>
|
|
|
|
|
|
</body>
|
|
</html> |