| <!doctype html> |
| <html class="docs-version-3.12" lang="en" dir="ltr"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <meta name="ahrefs-site-verification" content="c2f7370ecf46173f4fb25f114e74c97e0a2976d4f02f61c9b00a9d7d34e34698"> |
| <meta name="generator" content="Docusaurus v2.0.0-beta.6"> |
| <link rel="search" type="application/opensearchdescription+xml" title="Apache APISIX® -- Cloud-Native API Gateway and AI Gateway" href="/opensearch.xml"> |
| <script type="application/ld+json">{"@context":"https://schema.org","@type":"WebSite","name":"Apache APISIX","url":"https://apisix.apache.org"}</script> |
| <script src="https://widget.kapa.ai/kapa-widget.bundle.js" data-website-id="24b59d9a-682e-4c3d-9e83-bf2ee85cdc19" data-project-name="APISIX" data-project-color="#E8442E" data-project-logo="https://static.apiseven.com/202202/apache-apisix.png" data-modal-disclaimer="This is a custom LLM for APISIX with access to all developer documentation, GitHub issues and discussions." data-modal-example-questions="How to set up canary release in APISIX?,How to develop a custom APISIX plugin?,How to use custom NGINX configuration in APISIX?,How to configure mTLS between clients and APISIX?,How to only allow a specific APISIX consumer to access special services or routes?" async></script><title data-react-helmet="true">FAQ | Apache APISIX® -- Cloud-Native API Gateway and AI Gateway</title><meta data-react-helmet="true" property="og:image" content="https://static.apiseven.com/202202/apache-apisix.png"><meta data-react-helmet="true" name="twitter:image" content="https://static.apiseven.com/202202/apache-apisix.png"><meta data-react-helmet="true" property="og:url" content="https://apisix.apache.org/docs/apisix/3.12/FAQ/"><meta data-react-helmet="true" name="docsearch:language" content="en"><meta data-react-helmet="true" name="docsearch:version" content="3.12"><meta data-react-helmet="true" name="docsearch:docusaurus_tag" content="docs-docs-apisix-3.12"><meta data-react-helmet="true" name="robots" content="index,follow"><meta data-react-helmet="true" name="twitter:card" content="summary"><meta data-react-helmet="true" property="og:title" content="FAQ | Apache APISIX® -- Cloud-Native API Gateway and AI Gateway"><meta data-react-helmet="true" name="description" content="This article lists solutions to common problems when using Apache APISIX."><meta data-react-helmet="true" property="og:description" content="This article lists solutions to common problems when using Apache APISIX."><meta data-react-helmet="true" name="keywords" content="Apache APISIX,API Gateway,FAQ"><link data-react-helmet="true" rel="shortcut icon" href="https://static.apiseven.com/202202/favicon.png"><link data-react-helmet="true" rel="canonical" href="https://apisix.apache.org/docs/apisix/3.12/FAQ/"><link data-react-helmet="true" rel="alternate" href="https://apisix.apache.org/docs/apisix/3.12/FAQ/" hreflang="en"><link data-react-helmet="true" rel="alternate" href="https://apisix.apache.org/zh/docs/apisix/3.12/FAQ/" hreflang="zh"><link data-react-helmet="true" rel="alternate" href="https://apisix.apache.org/docs/apisix/3.12/FAQ/" hreflang="x-default"><link data-react-helmet="true" rel="preconnect" href="https://38VC84A2WJ-dsn.algolia.net" crossorigin="anonymous"><link rel="preload" href="https://static.apiseven.com/202202/MaisonNeue-Medium.otf" as="font" type="font/otf" crossorigin> |
| <link rel="preload" href="https://static.apiseven.com/202202/MaisonNeue-Bold.otf" as="font" type="font/otf" crossorigin> |
| <link rel="preload" href="https://static.apiseven.com/202202/MaisonNeue-Light.otf" as="font" type="font/otf" crossorigin> |
| <link rel="preload" href="https://static.apiseven.com/202202/MaisonNeue-Demi.otf" as="font" type="font/otf" crossorigin> |
| <link rel="preload" href="https://static.apiseven.com/202202/MaisonNeue-ExtraBold.otf" as="font" type="font/otf" crossorigin> |
| <link rel="preload" href="https://apisix-website-static.apiseven.com/assets/js/runtime~main.06b57428.js" as="script"> |
| <link rel="preload" href="https://apisix-website-static.apiseven.com/assets/js/main.3aedbf26.js" as="script"> |
| <link rel="stylesheet" href="https://apisix-website-static.apiseven.com/assets/css/styles.8de0825e.css"> |
| |
| <script>var _paq=window._paq=window._paq||[];_paq.push(["disableCookies"]),_paq.push(["trackPageView"]),_paq.push(["enableLinkTracking"]),function(){var a="https://analytics.apache.org/";_paq.push(["setTrackerUrl",a+"matomo.php"]),_paq.push(["setSiteId","17"]);var e=document,p=e.createElement("script"),t=e.getElementsByTagName("script")[0];p.async=!0,p.src=a+"matomo.js",t.parentNode.insertBefore(p,t)}()</script> |
| |
| </head> |
| <body> |
| <script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}(),document.documentElement.setAttribute("data-announcement-bar-initially-dismissed",function(){try{return"true"===localStorage.getItem("docusaurus.announcement.dismiss")}catch(t){}return!1}())</script><div id="__docusaurus"> |
| <div><a href="#" class="skipToContent_OuoZ">Skip to main content</a></div><div class="announcementBar_axC9" style="background-color:#e8433e;color:white" role="banner"><div class="announcementBarPlaceholder_xYHE"></div><div class="announcementBarContent_6uhP">🤔 Introducing APISIX AI Gateway – Built for LLMs and AI workloads. <a target="_blank" rel="noopener noreferrer" href="/ai-gateway/"> Learn More</a></div><button type="button" class="clean-btn close announcementBarClose_A3A1" aria-label="Close"><svg viewBox="0 0 24 24" width="14" height="14" fill="currentColor"><path d="M24 20.188l-8.315-8.209 8.2-8.282-3.697-3.697-8.212 8.318-8.31-8.203-3.666 3.666 8.321 8.24-8.206 8.313 3.666 3.666 8.237-8.318 8.285 8.203z"></path></svg></button></div><nav class="navbar navbar--fixed-top navbarHideable_RReh"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Navigation bar toggle" class="navbar__toggle clean-btn" type="button" tabindex="0"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a target="_parent" class="navbar__brand" href="/"><img src="/img/logo2.svg" alt="Apache APISIX®" class="themedImage_TMUO themedImage--light_4Vu1 navbar__logo"><img src="/img/logo2.svg" alt="Apache APISIX®" class="themedImage_TMUO themedImage--dark_uzRr navbar__logo"><b class="navbar__title">Apache APISIX®</b></a></div><div class="navbar__items navbar__items--right"><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a aria-current="page" class="navbar__link" target="_parent" href="/docs/">Docs</a><ul class="dropdown__menu"><li><a class="dropdown__link" target="_parent" href="/docs/apisix/getting-started/">Apache APISIX®️</a></li><li><a class="dropdown__link" target="_parent" href="/docs/apisix/next/dashboard/">Apache APISIX®️ Dashboard</a></li><li><a class="dropdown__link" target="_parent" href="/docs/ingress-controller/overview/">Apache APISIX®️ Ingress Controller</a></li><li><a class="dropdown__link" target="_parent" href="/docs/helm-chart/apisix/">Apache APISIX®️ Helm Charts</a></li><li><a class="dropdown__link" target="_parent" href="/docs/docker/build/">Apache APISIX®️ Docker</a></li><li><a class="dropdown__link" target="_parent" href="/docs/java-plugin-runner/development/">Apache APISIX®️ Java Plugin Runner</a></li><li><a class="dropdown__link" target="_parent" href="/docs/go-plugin-runner/getting-started/">Apache APISIX®️ Go Plugin Runner</a></li><li><a class="dropdown__link" target="_parent" href="/docs/python-plugin-runner/getting-started/">Apache APISIX®️ Python Plugin Runner</a></li><li><a class="dropdown__link" target="_parent" href="/docs/general/join/">General</a></li></ul></div><a class="navbar__item navbar__link" target="_parent" href="/blog/">Blog</a><a class="navbar__item navbar__link" target="_parent" href="/blog/tags/case-studies/">Case Studies</a><a class="navbar__item navbar__link" target="_parent" href="/downloads/">Downloads</a><a class="navbar__item navbar__link" target="_parent" href="/help/">Help</a><a class="navbar__item navbar__link" target="_parent" href="/team/">Team</a><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a class="navbar__link">Resources</a><ul class="dropdown__menu"><li><a class="dropdown__link" target="_parent" href="/showcase/">Showcase</a></li><li><a class="dropdown__link" target="_parent" href="/docs/general/code-samples/">Code Samples</a></li><li><a class="dropdown__link" target="_parent" href="/plugins/">PluginHub</a></li><li><a class="dropdown__link" target="_parent" href="/docs/general/join/">Community</a></li><li><a class="dropdown__link" target="_parent" href="/docs/general/events/">Events</a></li><li><a href="https://github.com/apache/apisix/milestones" target="_parent" rel="noopener noreferrer" class="dropdown__link">Roadmap</a></li></ul></div><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href="#" class="navbar__link"><span><svg viewBox="0 0 20 20" width="20" height="20" aria-hidden="true" class="iconLanguage_zID8"><path fill="currentColor" d="M19.753 10.909c-.624-1.707-2.366-2.726-4.661-2.726-.09 0-.176.002-.262.006l-.016-2.063 3.525-.607c.115-.019.133-.119.109-.231-.023-.111-.167-.883-.188-.976-.027-.131-.102-.127-.207-.109-.104.018-3.25.461-3.25.461l-.013-2.078c-.001-.125-.069-.158-.194-.156l-1.025.016c-.105.002-.164.049-.162.148l.033 2.307s-3.061.527-3.144.543c-.084.014-.17.053-.151.143.019.09.19 1.094.208 1.172.018.08.072.129.188.107l2.924-.504.035 2.018c-1.077.281-1.801.824-2.256 1.303-.768.807-1.207 1.887-1.207 2.963 0 1.586.971 2.529 2.328 2.695 3.162.387 5.119-3.06 5.769-4.715 1.097 1.506.256 4.354-2.094 5.98-.043.029-.098.129-.033.207l.619.756c.08.096.206.059.256.023 2.51-1.73 3.661-4.515 2.869-6.683zm-7.386 3.188c-.966-.121-.944-.914-.944-1.453 0-.773.327-1.58.876-2.156a3.21 3.21 0 011.229-.799l.082 4.277a2.773 2.773 0 01-1.243.131zm2.427-.553l.046-4.109c.084-.004.166-.01.252-.01.773 0 1.494.145 1.885.361.391.217-1.023 2.713-2.183 3.758zm-8.95-7.668a.196.196 0 00-.196-.145h-1.95a.194.194 0 00-.194.144L.008 16.916c-.017.051-.011.076.062.076h1.733c.075 0 .099-.023.114-.072l1.008-3.318h3.496l1.008 3.318c.016.049.039.072.113.072h1.734c.072 0 .078-.025.062-.076-.014-.05-3.083-9.741-3.494-11.04zm-2.618 6.318l1.447-5.25 1.447 5.25H3.226z"></path></svg><span>English</span></span></a><ul class="dropdown__menu"><li><a href="/docs/apisix/3.12/FAQ/" target="_self" rel="noopener noreferrer" class="dropdown__link dropdown__link--active" style="text-transform:capitalize">English</a></li><li><a href="/zh/docs/apisix/3.12/FAQ/" target="_self" rel="noopener noreferrer" class="dropdown__link" style="text-transform:capitalize">简体中文</a></li></ul></div><div class="react-toggle toggle_2i4l react-toggle--disabled"><div class="react-toggle-track" role="button" tabindex="-1"><div class="react-toggle-track-check"><span class="toggle_iYfV">🌜</span></div><div class="react-toggle-track-x"><span class="toggle_iYfV">🌞</span></div><div class="react-toggle-thumb"></div></div><input type="checkbox" class="react-toggle-screenreader-only" aria-label="Switch between dark and light mode"></div><div class="searchBox_fBfG"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div class="main-wrapper docs-wrapper docs-doc-page"><div class="docPage_GMj9"><button class="clean-btn backToTopButton_i9tI" type="button"><svg viewBox="0 0 24 24" width="28"><path d="M7.41 15.41L12 10.83l4.59 4.58L18 14l-6-6-6 6z" fill="currentColor"></path></svg></button><aside class="docSidebarContainer_k0Pq"><div class="sidebar_LIo8 sidebarWithHideableNavbar_CMI-"><a target="_parent" tabindex="-1" class="sidebarLogo_P87M" href="/"><img src="/img/logo2.svg" alt="Apache APISIX®" class="themedImage_TMUO themedImage--light_4Vu1"><img src="/img/logo2.svg" alt="Apache APISIX®" class="themedImage_TMUO themedImage--dark_uzRr"><b>Apache APISIX®</b></a><div class="sidebarVersionSwitch_0QIZ">Version:<div class="navbar__item dropdown dropdown--hoverable"><a class="navbar__link" href="/docs/apisix/3.12/getting-started/README/">3.12</a><ul class="dropdown__menu"><li><a class="dropdown__link" href="/docs/apisix/next/FAQ/"><div>Next</div></a></li><li><a class="dropdown__link" href="/docs/apisix/FAQ/"><div>3.14<div class="badge_6FVu Latest_oyqS">Latest</div></div></a></li><li><a class="dropdown__link" href="/docs/apisix/3.13/FAQ/"><div>3.13</div></a></li><li><a aria-current="page" class="dropdown__link dropdown__link--active" href="/docs/apisix/3.12/FAQ/"><div>3.12</div></a></li><li><a class="dropdown__link" href="/docs/apisix/3.11/FAQ/"><div>3.11</div></a></li><li><a class="dropdown__link" href="/docs/apisix/3.10/FAQ/"><div>3.10</div></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.9/getting-started/readme/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.9<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.8/getting-started/readme/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.8<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.7/getting-started/readme/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.7<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.6/getting-started/readme/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.6<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.5/getting-started/readme/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.5<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.4/getting-started/readme/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.4<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.3/getting-started/readme/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.3<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.2/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.2<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.1/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.1<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/3.0/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>3.0<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.15/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.15<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.14/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.14<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.13/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.13<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.12/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.12<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.11/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.11<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.10/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.10<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.9/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.9<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.8/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.8<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.7/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.7<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.6/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.6<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.5/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.5<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li><a href="https://apache-apisix.netlify.app/docs/apisix/2.4/getting-started/" target="_blank" rel="noopener noreferrer" class="dropdown__link"><span>2.4<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li></ul></div></div><nav class="menu thin-scrollbar menu_oAhv menuWithAnnouncementBar_IVfW"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-category menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#">Getting Started</a></li><li class="theme-doc-sidebar-item-link menu__list-item"><a class="menu__link" href="/docs/apisix/3.12/installation-guide/">Installation</a></li><li class="theme-doc-sidebar-item-link menu__list-item"><a class="menu__link" href="/docs/apisix/3.12/architecture-design/apisix/">Architecture</a></li><li class="theme-doc-sidebar-item-category menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#">Tutorials</a></li><li class="theme-doc-sidebar-item-category menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#">Terminology</a></li><li class="theme-doc-sidebar-item-category menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#">Plugins</a></li><li class="theme-doc-sidebar-item-category menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#">API</a></li><li class="theme-doc-sidebar-item-category menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#">Development</a></li><li class="theme-doc-sidebar-item-link menu__list-item"><a class="menu__link" href="/docs/apisix/3.12/deployment-modes/">Deployment modes</a></li><li class="theme-doc-sidebar-item-link menu__list-item"><a class="menu__link menu__link--active" aria-current="page" href="/docs/apisix/3.12/FAQ/">FAQ</a></li><li class="theme-doc-sidebar-item-category menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#">Others</a></li><li class="theme-doc-sidebar-item-link menu__list-item"><a href="https://github.com/apache/apisix/blob/master/CHANGELOG.md" target="_blank" rel="noopener noreferrer" class="menu__link"><span>CHANGELOG<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_wgqa"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></span></a></li><li class="theme-doc-sidebar-item-link menu__list-item"><a class="menu__link" href="/docs/apisix/3.12/upgrade-guide-from-2.15.x-to-3.0.0/">Upgrade Guide</a></li></ul></nav><button type="button" title="Collapse sidebar" aria-label="Collapse sidebar" class="button button--secondary button--outline collapseSidebarButton_EBxv"><svg width="20" height="20" aria-hidden="true" class="collapseSidebarButtonIcon_AF9Q"><g fill="#7a7a7a"><path d="M9.992 10.023c0 .2-.062.399-.172.547l-4.996 7.492a.982.982 0 01-.828.454H1c-.55 0-1-.453-1-1 0-.2.059-.403.168-.551l4.629-6.942L.168 3.078A.939.939 0 010 2.528c0-.548.45-.997 1-.997h2.996c.352 0 .649.18.828.45L9.82 9.472c.11.148.172.347.172.55zm0 0"></path><path d="M19.98 10.023c0 .2-.058.399-.168.547l-4.996 7.492a.987.987 0 01-.828.454h-3c-.547 0-.996-.453-.996-1 0-.2.059-.403.168-.551l4.625-6.942-4.625-6.945a.939.939 0 01-.168-.55 1 1 0 01.996-.997h3c.348 0 .649.18.828.45l4.996 7.492c.11.148.168.347.168.55zm0 0"></path></g></svg></button></div></aside><main class="docMainContainer_Q970"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_zHA2"><div class="theme-doc-version-banner alert alert--warning margin-bottom--md" role="alert"><div>This is documentation for Apache APISIX® -- Cloud-Native API Gateway and AI Gateway <b>3.12</b>, which is no longer actively maintained.</div><div class="margin-top--md">For up-to-date documentation, see the <b><a href="/docs/apisix/FAQ/">latest version</a></b> (3.14).</div></div><div class="docItemContainer_oiyr"><article><span class="theme-doc-version-badge badge badge--secondary">Version: 3.12</span><div class="tocCollapsible_aw-L theme-doc-toc-mobile tocMobile_Tx6Y"><button type="button" class="clean-btn tocCollapsibleButton_zr6a">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>FAQ</h1></header><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="why-do-i-need-a-new-api-gateway"></a>Why do I need a new API gateway?<a class="hash-link" href="#why-do-i-need-a-new-api-gateway" title="Direct link to heading">#</a></h2><p>As organizations move towards cloud native microservices, there is a need for an API gateway that is performant, flexible, secure and scalable.</p><p>APISIX outperforms other API gateways in these metrics while being platform agnostic and fully dynamic delivering features like supporting multiple protocols, fine-grained routing and multi-language support.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-does-apache-apisix-differ-from-other-api-gateways"></a>How does Apache APISIX differ from other API gateways?<a class="hash-link" href="#how-does-apache-apisix-differ-from-other-api-gateways" title="Direct link to heading">#</a></h2><p>Apache APISIX differs in the following ways:</p><ul><li>It uses etcd to save and synchronize configurations rather than relational databases like PostgreSQL or MySQL. The real-time event notification system in etcd is easier to scale than in these alternatives. This allows APISIX to synchronize the configuration in real-time, makes the code concise and avoids a single point of failure.</li><li>Fully dynamic.</li><li>Supports <a href="/docs/apisix/3.12/terminology/plugin/#hot-reload">hot loading of Plugins</a>.</li></ul><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="what-is-the-performance-impact-of-using-apache-apisix"></a>What is the performance impact of using Apache APISIX?<a class="hash-link" href="#what-is-the-performance-impact-of-using-apache-apisix" title="Direct link to heading">#</a></h2><p>Apache APISIX delivers the best performance among other API gateways with a single-core QPS of 18,000 with an average delay of 0.2 ms.</p><p>Specific results of the performance benchmarks can be found <a href="/docs/apisix/3.12/benchmark/">here</a>.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="which-platforms-does-apache-apisix-support"></a>Which platforms does Apache APISIX support?<a class="hash-link" href="#which-platforms-does-apache-apisix-support" title="Direct link to heading">#</a></h2><p>Apache APISIX is platform agnostic and avoids vendor lock-in. It is built for cloud native environments and can run on bare-metal machines to Kubernetes. It even support Apple Silicon chips.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="what-does-it-mean-by-apache-apisix-is-fully-dynamic"></a>What does it mean by "Apache APISIX is fully dynamic"?<a class="hash-link" href="#what-does-it-mean-by-apache-apisix-is-fully-dynamic" title="Direct link to heading">#</a></h2><p>Apache APISIX is fully dynamic in the sense that it doesn't require restarts to change its behavior.</p><p>It does the following dynamically:</p><ul><li>Reloading Plugins</li><li>Proxy rewrites</li><li>Proxy mirror</li><li>Response rewrites</li><li>Health checks</li><li>Traffic split</li></ul><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="does-apache-apisix-have-a-user-interface"></a>Does Apache APISIX have a user interface?<a class="hash-link" href="#does-apache-apisix-have-a-user-interface" title="Direct link to heading">#</a></h2><p>Yes. Apache APISIX has an experimental feature called <a href="https://github.com/apache/apisix-dashboard" rel="noopener noreferrer">Apache APISIX Dashboard</a>, which is independent from Apache APISIX. To work with Apache APISIX through a user interface, you can deploy the Apache APISIX Dashboard.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="can-i-write-my-own-plugins-for-apache-apisix"></a>Can I write my own Plugins for Apache APISIX?<a class="hash-link" href="#can-i-write-my-own-plugins-for-apache-apisix" title="Direct link to heading">#</a></h2><p>Yes. Apache APISIX is flexible and extensible through the use of custom Plugins that can be specific to user needs.</p><p>You can write your own Plugins by referring to <a href="/docs/apisix/3.12/plugin-develop/">How to write your own Plugins</a>.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="why-does-apache-apisix-use-etcd-for-the-configuration-center"></a>Why does Apache APISIX use etcd for the configuration center?<a class="hash-link" href="#why-does-apache-apisix-use-etcd-for-the-configuration-center" title="Direct link to heading">#</a></h2><p>In addition to the basic functionality of storing the configurations, Apache APISIX also needs a storage system that supports these features:</p><ol><li>Distributed deployments in clusters.</li><li>Guarded transactions by comparisons.</li><li>Multi-version concurrency control.</li><li>Notifications and watch streams.</li><li>High performance with minimum read/write latency.</li></ol><p>etcd provides these features and more making it ideal over other databases like PostgreSQL and MySQL.</p><p>To learn more on how etcd compares with other alternatives see this <a href="https://etcd.io/docs/latest/learning/why/#comparison-chart" target="_blank" rel="noopener noreferrer">comparison chart</a>.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="when-installing-apache-apisix-dependencies-with-luarocks-why-does-it-cause-a-timeout-or-result-in-a-slow-or-unsuccessful-installation"></a>When installing Apache APISIX dependencies with LuaRocks, why does it cause a timeout or result in a slow or unsuccessful installation?<a class="hash-link" href="#when-installing-apache-apisix-dependencies-with-luarocks-why-does-it-cause-a-timeout-or-result-in-a-slow-or-unsuccessful-installation" title="Direct link to heading">#</a></h2><p>This is likely because the LuaRocks server used is blocked.</p><p>To solve this you can use https_proxy or use the <code>--server</code> flag to specify a faster LuaRocks server.</p><p>You can run the command below to see the available servers (needs LuaRocks 3.0+):</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">luarocks config rocks_servers</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>Mainland China users can use <code>luarocks.cn</code> as the LuaRocks server. You can use this wrapper with the Makefile to set this up:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">make</span><span class="token plain"> deps </span><span class="token assign-left variable" style="color:#36acaa">ENV_LUAROCKS_SERVER</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">https://luarocks.cn</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>If this does not solve your problem, you can try getting a detailed log by using the <code>--verbose</code> or <code>-v</code> flag to diagnose the problem.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-do-i-build-the-apisix-runtime-environment"></a>How do I build the APISIX-Runtime environment?<a class="hash-link" href="#how-do-i-build-the-apisix-runtime-environment" title="Direct link to heading">#</a></h2><p>Some functions need to introduce additional NGINX modules, which requires APISIX to run on APISIX-Runtime. If you need these functions, you can refer to the code in <a href="https://github.com/api7/apisix-build-tools" rel="noopener noreferrer">api7/apisix-build-tools</a> to build your own APISIX-Runtime environment.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-can-i-make-a-gray-release-with-apache-apisix"></a>How can I make a gray release with Apache APISIX?<a class="hash-link" href="#how-can-i-make-a-gray-release-with-apache-apisix" title="Direct link to heading">#</a></h2><p>Let's take an example query <code>foo.com/product/index.html?id=204&page=2</code> and consider that you need to make a gray release based on the <code>id</code> in the query string with this condition:</p><ol><li>Group A: <code>id <= 1000</code></li><li>Group B: <code>id > 1000</code></li></ol><p>There are two different ways to achieve this in Apache APISIX:</p><div class="admonition admonition-note alert alert--secondary"><div class="admonition-heading"><h5><span class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" width="14" height="16" viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</h5></div><div class="admonition-content"><p>You can fetch the <code>admin_key</code> from <code>config.yaml</code> and save to an environment variable with the following command:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token assign-left variable" style="color:#36acaa">admin_key</span><span class="token operator" style="color:#393A34">=</span><span class="token variable" style="color:#36acaa">$(</span><span class="token variable" style="color:#36acaa">yq </span><span class="token variable string" style="color:#e3116c">'.deployment.admin.admin_key[0].key'</span><span class="token variable" style="color:#36acaa"> conf/config.yaml </span><span class="token variable operator" style="color:#393A34">|</span><span class="token variable" style="color:#36acaa"> </span><span class="token variable function" style="color:#d73a49">sed</span><span class="token variable" style="color:#36acaa"> </span><span class="token variable string" style="color:#e3116c">'s/"//g'</span><span class="token variable" style="color:#36acaa">)</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></div></div><ol><li>Using the <code>vars</code> field in a <a href="/docs/apisix/3.12/terminology/route/">Route</a>:</li></ol><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> -i http://127.0.0.1:9180/apisix/admin/routes/1 -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/index.html",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "vars": [</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> ["arg_id", "<=", "1000"]</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> ],</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "plugins": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "redirect": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/test?group_id=1"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> -i http://127.0.0.1:9180/apisix/admin/routes/2 -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/index.html",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "vars": [</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> ["arg_id", ">", "1000"]</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> ],</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "plugins": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "redirect": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/test?group_id=2"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>All the available operators of the current <code>lua-resty-radixtree</code> are listed <a href="https://github.com/api7/lua-resty-radixtree#operator-list" target="_blank" rel="noopener noreferrer">here</a>.</p><ol start="2"><li>Using the <a href="/docs/apisix/3.12/plugins/traffic-split/">traffic-split</a> Plugin.</li></ol><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-do-i-redirect-http-traffic-to-https-with-apache-apisix"></a>How do I redirect HTTP traffic to HTTPS with Apache APISIX?<a class="hash-link" href="#how-do-i-redirect-http-traffic-to-https-with-apache-apisix" title="Direct link to heading">#</a></h2><p>For example, you need to redirect traffic from <code>http://foo.com</code> to <code>https://foo.com</code>.</p><p>Apache APISIX provides several different ways to achieve this:</p><ol><li>Setting <code>http_to_https</code> to <code>true</code> in the <a href="/docs/apisix/3.12/plugins/redirect/">redirect</a> Plugin:</li></ol><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/routes/1 -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/hello",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "host": "foo.com",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "plugins": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "redirect": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "http_to_https": true</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><ol start="2"><li>Advanced routing with <code>vars</code> in the redirect Plugin:</li></ol><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> -i http://127.0.0.1:9180/apisix/admin/routes/1 -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/hello",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "host": "foo.com",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "vars": [</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> [</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "scheme",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "==",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "http"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> ]</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> ],</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "plugins": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "redirect": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "https://$host$request_uri",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "ret_code": 301</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><ol start="3"><li>Using the <code>serverless</code> Plugin:</li></ol><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> -i http://127.0.0.1:9180/apisix/admin/routes/1 -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/hello",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "plugins": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "serverless-pre-function": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "phase": "rewrite",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "functions": ["return function() if ngx.var.scheme == \"http\" and ngx.var.host == \"foo.com\" then ngx.header[\"Location\"] = \"https://foo.com\" .. ngx.var.request_uri; ngx.exit(ngx.HTTP_MOVED_PERMANENTLY); end; end"]</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>To test this serverless Plugin:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> -i -H </span><span class="token string" style="color:#e3116c">'Host: foo.com'</span><span class="token plain"> http://127.0.0.1:9080/hello</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>The response should be:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">301</span><span class="token plain"> Moved Permanently</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Date: Mon, </span><span class="token number" style="color:#36acaa">18</span><span class="token plain"> May </span><span class="token number" style="color:#36acaa">2020</span><span class="token plain"> 02:56:04 GMT</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Content-Type: text/html</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Content-Length: </span><span class="token number" style="color:#36acaa">166</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Connection: keep-alive</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Location: https://foo.com/hello</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Server: APISIX web server</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token operator" style="color:#393A34"><</span><span class="token plain">html</span><span class="token operator" style="color:#393A34">></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token operator" style="color:#393A34"><</span><span class="token plain">head</span><span class="token operator" style="color:#393A34">></span><span class="token operator" style="color:#393A34"><</span><span class="token plain">title</span><span class="token operator" style="color:#393A34">></span><span class="token number" style="color:#36acaa">301</span><span class="token plain"> Moved Permanently</span><span class="token operator" style="color:#393A34"><</span><span class="token plain">/title</span><span class="token operator" style="color:#393A34">></span><span class="token operator" style="color:#393A34"><</span><span class="token plain">/head</span><span class="token operator" style="color:#393A34">></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token operator" style="color:#393A34"><</span><span class="token plain">body</span><span class="token operator" style="color:#393A34">></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token operator" style="color:#393A34"><</span><span class="token plain">center</span><span class="token operator" style="color:#393A34">></span><span class="token operator" style="color:#393A34"><</span><span class="token plain">h</span><span class="token operator file-descriptor important" style="color:#393A34">1</span><span class="token operator" style="color:#393A34">></span><span class="token number" style="color:#36acaa">301</span><span class="token plain"> Moved Permanently</span><span class="token operator" style="color:#393A34"><</span><span class="token plain">/h</span><span class="token operator file-descriptor important" style="color:#393A34">1</span><span class="token operator" style="color:#393A34">></span><span class="token operator" style="color:#393A34"><</span><span class="token plain">/center</span><span class="token operator" style="color:#393A34">></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token operator" style="color:#393A34"><</span><span class="token plain">hr</span><span class="token operator" style="color:#393A34">></span><span class="token operator" style="color:#393A34"><</span><span class="token plain">center</span><span class="token operator" style="color:#393A34">></span><span class="token plain">openresty</span><span class="token operator" style="color:#393A34"><</span><span class="token plain">/center</span><span class="token operator" style="color:#393A34">></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token operator" style="color:#393A34"><</span><span class="token plain">/body</span><span class="token operator" style="color:#393A34">></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token operator" style="color:#393A34"><</span><span class="token plain">/html</span><span class="token operator" style="color:#393A34">></span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-do-i-change-apache-apisixs-log-level"></a>How do I change Apache APISIX's log level?<a class="hash-link" href="#how-do-i-change-apache-apisixs-log-level" title="Direct link to heading">#</a></h2><p>By default the log level of Apache APISIX is set to <code>warn</code>. You can set this to <code>info</code> to trace the messages printed by <code>core.log.info</code>.</p><p>For this, you can set the <code>error_log_level</code> parameter in your configuration file (conf/config.yaml) as shown below and reload Apache APISIX.</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 yaml"><pre tabindex="0" class="prism-code language-yaml codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token key atrule" style="color:#00a4db">nginx_config</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">error_log_level</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"info"</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-do-i-reload-my-custom-plugins-for-apache-apisix"></a>How do I reload my custom Plugins for Apache APISIX?<a class="hash-link" href="#how-do-i-reload-my-custom-plugins-for-apache-apisix" title="Direct link to heading">#</a></h2><p>All Plugins in Apache APISIX are hot reloaded.</p><p>You can learn more about hot reloading of Plugins <a href="/docs/apisix/3.12/terminology/plugin/#hot-reload">here</a>.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-do-i-configure-apache-apisix-to-listen-on-multiple-ports-when-handling-http-or-https-requests"></a>How do I configure Apache APISIX to listen on multiple ports when handling HTTP or HTTPS requests?<a class="hash-link" href="#how-do-i-configure-apache-apisix-to-listen-on-multiple-ports-when-handling-http-or-https-requests" title="Direct link to heading">#</a></h2><p>By default, Apache APISIX listens only on port 9080 when handling HTTP requests.</p><p>To configure Apache APISIX to listen on multiple ports, you can:</p><ol><li><p>Modify the parameter <code>node_listen</code> in <code>conf/config.yaml</code>:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain"> apisix:</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> node_listen:</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> - </span><span class="token number" style="color:#36acaa">9080</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> - </span><span class="token number" style="color:#36acaa">9081</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> - </span><span class="token number" style="color:#36acaa">9082</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>Similarly for HTTPS requests, modify the parameter <code>ssl.listen</code> in <code>conf/config.yaml</code>:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">apisix:</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> ssl:</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> enable: </span><span class="token boolean" style="color:#36acaa">true</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> listen:</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> - port: </span><span class="token number" style="color:#36acaa">9443</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> - port: </span><span class="token number" style="color:#36acaa">9444</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> - port: </span><span class="token number" style="color:#36acaa">9445</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li><li><p>Reload or restart Apache APISIX.</p></li></ol><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="after-uploading-the-ssl-certificate-why-cant-the-corresponding-route-be-accessed-through-https--ip"></a>After uploading the SSL certificate, why can't the corresponding route be accessed through HTTPS + IP?<a class="hash-link" href="#after-uploading-the-ssl-certificate-why-cant-the-corresponding-route-be-accessed-through-https--ip" title="Direct link to heading">#</a></h2><p>If you directly use HTTPS + IP address to access the server, the server will use the IP address to compare with the bound SNI. Since the SSL certificate is bound to the domain name, the corresponding resource cannot be found in the SNI, so that the certificate will be verified. The authentication fails, and the user cannot access the gateway via HTTPS + IP.</p><p>You can implement this function by setting the <code>fallback_sni</code> parameter in the configuration file and configuring the domain name. When the user uses HTTPS + IP to access the gateway, when the SNI is empty, it will fall back to the default SNI to achieve HTTPS + IP access to the gateway.</p><div class="codeBlockContainer_EiTO"><div style="color:#393A34;background-color:#f6f8fa" class="codeBlockTitle_PQMO">./conf/config.yaml</div><div class="codeBlockContent_X2I6 yaml"><pre tabindex="0" class="prism-code language-yaml codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">apisix</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> ssl：</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">fallback_sni</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"${your sni}"</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-does-apache-apisix-achieve-millisecond-level-configuration-synchronization"></a>How does Apache APISIX achieve millisecond-level configuration synchronization?<a class="hash-link" href="#how-does-apache-apisix-achieve-millisecond-level-configuration-synchronization" title="Direct link to heading">#</a></h2><p>Apache APISIX uses etcd for its configuration center. etcd provides subscription functions like <a href="https://github.com/api7/lua-resty-etcd/blob/master/api_v3.md#watch" target="_blank" rel="noopener noreferrer">watch</a> and <a href="https://github.com/api7/lua-resty-etcd/blob/master/api_v3.md#watchdir" target="_blank" rel="noopener noreferrer">watchdir</a> that can monitor changes to specific keywords or directories.</p><p>In Apache APISIX, we use <a href="https://github.com/api7/lua-resty-etcd/blob/master/api_v3.md#watchdir" target="_blank" rel="noopener noreferrer">etcd.watchdir</a> to monitor changes in a directory.</p><p>If there is no change in the directory being monitored, the process will be blocked until it times out or run into any errors.</p><p>If there are changes in the directory being monitored, etcd will return this new data within milliseconds and Apache APISIX will update the cache memory.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-do-i-customize-the-apache-apisix-instance-id"></a>How do I customize the Apache APISIX instance id?<a class="hash-link" href="#how-do-i-customize-the-apache-apisix-instance-id" title="Direct link to heading">#</a></h2><p>By default, Apache APISIX reads the instance id from <code>conf/apisix.uid</code>. If this is not found and no id is configured, Apache APISIX will generate a <code>uuid</code> for the instance id.</p><p>To specify a meaningful id to bind Apache APISIX to your internal system, set the <code>id</code> in your <code>conf/config.yaml</code> file:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 yaml"><pre tabindex="0" class="prism-code language-yaml codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token key atrule" style="color:#00a4db">apisix</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">id</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"your-id"</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="why-are-there-errors-saying-failed-to-fetch-data-from-etcd-failed-to-read-etcd-dir-etcd-key-xxxxxx-in-the-errorlog"></a>Why are there errors saying "failed to fetch data from etcd, failed to read etcd dir, etcd key: xxxxxx" in the error.log?<a class="hash-link" href="#why-are-there-errors-saying-failed-to-fetch-data-from-etcd-failed-to-read-etcd-dir-etcd-key-xxxxxx-in-the-errorlog" title="Direct link to heading">#</a></h2><p>Please follow the troubleshooting steps described below:</p><ol><li><p>Make sure that there aren't any networking issues between Apache APISIX and your etcd deployment in your cluster.</p></li><li><p>If your network is healthy, check whether you have enabled the <a href="https://etcd.io/docs/v3.4/dev-guide/api_grpc_gateway/" target="_blank" rel="noopener noreferrer">gRPC gateway</a> for etcd. The default state depends on whether you used command line options or a configuration file to start the etcd server.</p><ul><li>If you used command line options, gRPC gateway is enabled by default. You can enable it manually as shown below:</li></ul><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 sh"><pre tabindex="0" class="prism-code language-sh codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">etcd --enable-grpc-gateway --data-dir=/path/to/data</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p><strong>Note</strong>: This flag is not shown while running <code>etcd --help</code>.</p><ul><li>If you used a configuration file, gRPC gateway is disabled by default. You can manually enable it as shown below:</li></ul><p>In <code>etcd.json</code>:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 json"><pre tabindex="0" class="prism-code language-json codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"enable-grpc-gateway"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token boolean" style="color:#36acaa">true</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#36acaa">"data-dir"</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/path/to/data"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>In <code>etcd.conf.yml</code>:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 yml"><pre tabindex="0" class="prism-code language-yml codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token key atrule" style="color:#00a4db">enable-grpc-gateway</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token boolean important" style="color:#36acaa">true</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div></li></ol><p><strong>Note</strong>: This distinction was eliminated by etcd in their latest master branch but wasn't backported to previous versions.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-do-i-setup-high-availability-apache-apisix-clusters"></a>How do I setup high availability Apache APISIX clusters?<a class="hash-link" href="#how-do-i-setup-high-availability-apache-apisix-clusters" title="Direct link to heading">#</a></h2><p>Apache APISIX can be made highly available by adding a load balancer in front of it as APISIX's data plane is stateless and can be scaled when needed.</p><p>The control plane of Apache APISIX is highly available as it relies only on an etcd cluster.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="why-does-the-make-deps-command-fail-when-installing-apache-apisix-from-source"></a>Why does the <code>make deps</code> command fail when installing Apache APISIX from source?<a class="hash-link" href="#why-does-the-make-deps-command-fail-when-installing-apache-apisix-from-source" title="Direct link to heading">#</a></h2><p>When executing <code>make deps</code> to install Apache APISIX from source, you can get an error as shown below:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">$ </span><span class="token function" style="color:#d73a49">make</span><span class="token plain"> deps</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token punctuation" style="color:#393A34">..</span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Error: Failed installing dependency: https://luarocks.org/luasec-0.9-1.src.rock - Could not </span><span class="token function" style="color:#d73a49">find</span><span class="token plain"> header </span><span class="token function" style="color:#d73a49">file</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">for</span><span class="token plain"> OPENSSL</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> No </span><span class="token function" style="color:#d73a49">file</span><span class="token plain"> openssl/ssl.h </span><span class="token keyword" style="color:#00009f">in</span><span class="token plain"> /usr/local/include</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">You may have to </span><span class="token function" style="color:#d73a49">install</span><span class="token plain"> OPENSSL </span><span class="token keyword" style="color:#00009f">in</span><span class="token plain"> your system and/or pass OPENSSL_DIR or OPENSSL_INCDIR to the luarocks command.</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Example: luarocks </span><span class="token function" style="color:#d73a49">install</span><span class="token plain"> luasec </span><span class="token assign-left variable" style="color:#36acaa">OPENSSL_DIR</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">/usr/local</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">make: *** </span><span class="token punctuation" style="color:#393A34">[</span><span class="token plain">deps</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"> Error </span><span class="token number" style="color:#36acaa">1</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>This is caused by the missing OpenResty openssl development kit. To install it, refer <a href="/docs/apisix/3.12/install-dependencies/">installing dependencies</a>.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-do-i-access-the-apisix-dashboard-through-apache-apisix-proxy"></a>How do I access the APISIX Dashboard through Apache APISIX proxy?<a class="hash-link" href="#how-do-i-access-the-apisix-dashboard-through-apache-apisix-proxy" title="Direct link to heading">#</a></h2><p>You can follow the steps below to configure this:</p><ol><li>Configure different ports for Apache APISIX proxy and Admin API. Or, disable the Admin API.</li></ol><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 yaml"><pre tabindex="0" class="prism-code language-yaml codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token key atrule" style="color:#00a4db">deployment</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">admin</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">admin_listen</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic"># use a separate port</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">ip</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> 127.0.0.1</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">port</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">9180</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><ol start="2"><li>Add a proxy Route for the Apache APISIX dashboard:</li></ol><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> -i http://127.0.0.1:9180/apisix/admin/routes/1 -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uris":[ "/*" ],</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "name":"apisix_proxy_dashboard",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream":{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes":[</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "host":"127.0.0.1",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "port":9000,</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "weight":1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> ],</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "type":"roundrobin"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p><strong>Note</strong>: The Apache APISIX Dashboard is listening on <code>127.0.0.1:9000</code>.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-do-i-use-regular-expressions-regex-for-matching-uri-in-a-route"></a>How do I use regular expressions (regex) for matching <code>uri</code> in a Route?<a class="hash-link" href="#how-do-i-use-regular-expressions-regex-for-matching-uri-in-a-route" title="Direct link to heading">#</a></h2><p>You can use the <code>vars</code> field in a Route for matching regular expressions:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> -i http://127.0.0.1:9180/apisix/admin/routes/1 -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/*",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "vars": [</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> ["uri", "~~", "^/[a-z]+$"]</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> ],</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "type": "roundrobin",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:1980": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>And to test this request:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic"># uri matched</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">$ </span><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9080/hello -i</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic"># uri didn't match</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">$ </span><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9080/12ab -i</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">404</span><span class="token plain"> Not Found</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>For more info on using <code>vars</code> refer to <a href="https://github.com/api7/lua-resty-expr" target="_blank" rel="noopener noreferrer">lua-resty-expr</a>.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="does-the-upstream-node-support-configuring-a-fqdn-address"></a>Does the Upstream node support configuring a <a href="https://en.wikipedia.org/wiki/Fully_qualified_domain_name" target="_blank" rel="noopener noreferrer">FQDN</a> address?<a class="hash-link" href="#does-the-upstream-node-support-configuring-a-fqdn-address" title="Direct link to heading">#</a></h2><p>Yes. The example below shows configuring the FQDN <code>httpbin.default.svc.cluster.local</code> (a Kubernetes service):</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/routes/1 -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/ip",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "type": "roundrobin",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "httpbin.default.svc.cluster.local": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>To test this Route:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">$ </span><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9080/ip -i</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="what-is-the-x-api-key-of-the-admin-api-can-it-be-modified"></a>What is the <code>X-API-KEY</code> of the Admin API? Can it be modified?<a class="hash-link" href="#what-is-the-x-api-key-of-the-admin-api-can-it-be-modified" title="Direct link to heading">#</a></h2><p><code>X-API-KEY</code> of the Admin API refers to the <code>apisix.admin_key.key</code> in your <code>conf/config.yaml</code> file. It is the access token for the Admin API.</p><p>By default, it is set to <code>edd1c9f034335f136f87ad84b625c8f1</code> and can be modified by changing the parameter in your <code>conf/config.yaml</code> file:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 yaml"><pre tabindex="0" class="prism-code language-yaml codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token key atrule" style="color:#00a4db">apisix</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> admin_key</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">-</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">name</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"admin"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">key</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> newkey</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">role</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> admin</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>Now, to access the Admin API:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">$ </span><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> -i http://127.0.0.1:9180/apisix/admin/routes/1 -H </span><span class="token string" style="color:#e3116c">'X-API-KEY: newkey'</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uris":[ "/*" ],</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "name":"admin-token-test",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream":{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes":[</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "host":"127.0.0.1",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "port":1980,</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "weight":1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> ],</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "type":"roundrobin"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token punctuation" style="color:#393A34">..</span><span class="token punctuation" style="color:#393A34">..</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p><strong>Note</strong>: By using the default token, you could be exposed to security risks. It is required to update it when deploying to a production environment.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-do-i-allow-all-ips-to-access-apache-apisixs-admin-api"></a>How do I allow all IPs to access Apache APISIX's Admin API?<a class="hash-link" href="#how-do-i-allow-all-ips-to-access-apache-apisixs-admin-api" title="Direct link to heading">#</a></h2><p>By default, Apache APISIX only allows IPs in the range <code>127.0.0.0/24</code> to access the Admin API.</p><p>To allow IPs in all ranges, you can update your configuration file as show below and restart or reload Apache APISIX.</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 yaml"><pre tabindex="0" class="prism-code language-yaml codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token key atrule" style="color:#00a4db">deployment</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">admin</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">allow_admin</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">-</span><span class="token plain"> 0.0.0.0/0</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p><strong>Note</strong>: This should only be used in non-production environments to allow all clients to access Apache APISIX and is not safe for production environments. Always authorize specific IP addresses or address ranges for production environments.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-do-i-auto-renew-ssl-certificates-with-acmesh"></a>How do I auto renew SSL certificates with acme.sh?<a class="hash-link" href="#how-do-i-auto-renew-ssl-certificates-with-acmesh" title="Direct link to heading">#</a></h2><p>You can run the commands below to achieve this:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> --output /root/.acme.sh/renew-hook-update-apisix.sh --silent https://gist.githubusercontent.com/anjia0532/9ebf8011322f43e3f5037bc2af3aeaa6/raw/65b359a4eed0ae990f9188c2afa22bacd8471652/renew-hook-update-apisix.sh</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">chmod</span><span class="token plain"> +x /root/.acme.sh/renew-hook-update-apisix.sh</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">acme.sh --issue --staging -d demo.domain --renew-hook </span><span class="token string" style="color:#e3116c">"/root/.acme.sh/renew-hook-update-apisix.sh -h http://apisix-admin:port -p /root/.acme.sh/demo.domain/demo.domain.cer -k /root/.acme.sh/demo.domain/demo.domain.key -a xxxxxxxxxxxxx"</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 bash"><pre tabindex="0" class="prism-code language-bash codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain">acme.sh --renew --domain demo.domain</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>You can check <a href="https://juejin.cn/post/6965778290619449351" target="_blank" rel="noopener noreferrer">this post</a> for a more detailed instruction on setting this up.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-do-i-strip-a-prefix-from-a-path-before-forwarding-to-upstream-in-apache-apisix"></a>How do I strip a prefix from a path before forwarding to Upstream in Apache APISIX?<a class="hash-link" href="#how-do-i-strip-a-prefix-from-a-path-before-forwarding-to-upstream-in-apache-apisix" title="Direct link to heading">#</a></h2><p>To strip a prefix from a path in your route, like to take <code>/foo/get</code> and strip it to <code>/get</code>, you can use the <a href="/docs/apisix/3.12/plugins/proxy-rewrite/">proxy-rewrite</a> Plugin:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> -i http://127.0.0.1:9180/apisix/admin/routes/1 -H </span><span class="token string" style="color:#e3116c">"X-API-KEY: </span><span class="token string variable" style="color:#36acaa">$admin_key</span><span class="token string" style="color:#e3116c">"</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/foo/*",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "plugins": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "proxy-rewrite": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "regex_uri": ["^/foo/(.*)","/$1"]</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> },</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "type": "roundrobin",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "httpbin.org:80": 1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>And to test this configuration:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9080/foo/get -i</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">HTTP/1.1 </span><span class="token number" style="color:#36acaa">200</span><span class="token plain"> OK</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">..</span><span class="token plain">.</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#e3116c">"url"</span><span class="token builtin class-name">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"http://127.0.0.1/get"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-do-i-fix-the-error-unable-to-get-local-issuer-certificate-in-apache-apisix"></a>How do I fix the error <code>unable to get local issuer certificate</code> in Apache APISIX?<a class="hash-link" href="#how-do-i-fix-the-error-unable-to-get-local-issuer-certificate-in-apache-apisix" title="Direct link to heading">#</a></h2><p>You can manually set the path to your certificate by adding it to your <code>conf/config.yaml</code> file as shown below:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 yaml"><pre tabindex="0" class="prism-code language-yaml codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token key atrule" style="color:#00a4db">apisix</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">ssl</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">ssl_trusted_certificate</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> /path/to/certs/ca</span><span class="token punctuation" style="color:#393A34">-</span><span class="token plain">certificates.crt</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p><strong>Note</strong>: When you are trying to connect TLS services with cosocket and if APISIX does not trust the peer's TLS certificate, you should set the parameter <code>apisix.ssl.ssl_trusted_certificate</code>.</p><p>For example, if you are using Nacos for service discovery in APISIX, and Nacos has TLS enabled (configured host starts with <code>https://</code>), you should set <code>apisix.ssl.ssl_trusted_certificate</code> and use the same CA certificate as Nacos.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-do-i-fix-the-error-module-restyworkerevents-not-found-in-apache-apisix"></a>How do I fix the error <code>module 'resty.worker.events' not found</code> in Apache APISIX?<a class="hash-link" href="#how-do-i-fix-the-error-module-restyworkerevents-not-found-in-apache-apisix" title="Direct link to heading">#</a></h2><p>This error is caused by installing Apache APISIX in the <code>/root</code> directory. The worker process would by run by the user "nobody" and it would not have enough permissions to access the files in the <code>/root</code> directory.</p><p>To fix this, you can change the APISIX installation directory to the recommended directory: <code>/usr/local</code>.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix"></a>What is the difference between <code>plugin-metadata</code> and <code>plugin-configs</code> in Apache APISIX?<a class="hash-link" href="#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix" title="Direct link to heading">#</a></h2><p>The differences between the two are described in the table below:</p><table><thead><tr><th><code>plugin-metadata</code></th><th><code>plugin-config</code></th></tr></thead><tbody><tr><td>Metadata of a Plugin shared by all configuration instances of the Plugin.</td><td>Collection of configuration instances of multiple different Plugins.</td></tr><tr><td>Used when there are property changes that needs to be propagated across all configuration instances of a Plugin.</td><td>Used when you need to reuse a common set of configuration instances so that it can be extracted to a <code>plugin-config</code> and bound to different Routes.</td></tr><tr><td>Takes effect on all the entities bound to the configuration instances of the Plugin.</td><td>Takes effect on Routes bound to the <code>plugin-config</code>.</td></tr></tbody></table><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="after-deploying-apache-apisix-how-to-detect-the-survival-of-the-apisix-data-plane"></a>After deploying Apache APISIX, how to detect the survival of the APISIX data plane?<a class="hash-link" href="#after-deploying-apache-apisix-how-to-detect-the-survival-of-the-apisix-data-plane" title="Direct link to heading">#</a></h2><p>You can create a route named <code>health-info</code> and enable the <a href="https://apisix.apache.org/docs/apisix/plugins/fault-injection/" rel="noopener noreferrer">fault-injection</a> plugin (where YOUR-TOKEN is the user's token; 127.0.0.1 is the IP address of the control plane, which can be modified by yourself):</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/routes/health-info </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">'X-API-KEY: YOUR-TOKEN'</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "plugins": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "fault-injection": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "abort": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "http_status": 200,</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "body": "fine"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> },</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri": "/status"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>Verification:</p><p>Access the <code>/status</code> of the Apache APISIX data plane to detect APISIX. If the response code is 200, it means APISIX is alive.</p><div class="admonition admonition-note alert alert--secondary"><div class="admonition-heading"><h5><span class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" width="14" height="16" viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</h5></div><div class="admonition-content"><p>This method only detects whether the APISIX data plane is alive or not. It does not mean that the routing and other functions of APISIX are normal. These require more routing-level detection.</p></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="what-are-the-scenarios-with-high-apisix-latency-related-to-etcd-and-how-to-fix-them"></a>What are the scenarios with high APISIX latency related to <a href="https://etcd.io/" target="_blank" rel="noopener noreferrer">etcd</a> and how to fix them?<a class="hash-link" href="#what-are-the-scenarios-with-high-apisix-latency-related-to-etcd-and-how-to-fix-them" title="Direct link to heading">#</a></h2><p>etcd is the data storage component of apisix, and its stability is related to the stability of APISIX.</p><p>In actual scenarios, if APISIX uses a certificate to connect to etcd through HTTPS, the following two problems of high latency for data query or writing may occur:</p><ol><li>Query or write data through APISIX Admin API.</li><li>In the monitoring scenario, Prometheus crawls the APISIX data plane Metrics API timeout.</li></ol><p>These problems related to higher latency seriously affect the service stability of APISIX, and the reason why such problems occur is mainly because etcd provides two modes of operation: HTTP (HTTPS) and gRPC. And APISIX uses the HTTP (HTTPS) protocol to operate etcd by default. |
| In this scenario, etcd has a bug about HTTP/2: if etcd is operated over HTTPS (HTTP is not affected), the upper limit of HTTP/2 connections is the default <code>250</code> in Golang. Therefore, when the number of APISIX data plane nodes is large, once the number of connections between all APISIX nodes and etcd exceeds this upper limit, the response of APISIX API interface will be very slow.</p><p>In Golang, the default upper limit of HTTP/2 connections is <code>250</code>, the code is as follows:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 go"><pre tabindex="0" class="prism-code language-go codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">package</span><span class="token plain"> http2</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">...</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">const</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> prefaceTimeout </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">10</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">*</span><span class="token plain"> time</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">Second</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> firstSettingsTimeout </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">2</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">*</span><span class="token plain"> time</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">Second </span><span class="token comment" style="color:#999988;font-style:italic">// should be in-flight with preface anyway</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> handlerChunkWriteSize </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">4</span><span class="token plain"> </span><span class="token operator" style="color:#393A34"><<</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">10</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> defaultMaxStreams </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">250</span><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic">// TODO: make this 100 as the GFE seems to?</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> maxQueuedControlFrames </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">10000</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>etcd officially maintains two main branches, <code>3.4</code> and <code>3.5</code>. In the <code>3.4</code> series, the recently released <code>3.4.20</code> version has fixed this issue. As for the <code>3.5</code> version, the official is preparing to release the <code>3.5.5</code> version a long time ago, but it has not been released as of now (2022.09.13). So, if you are using etcd version less than <code>3.5.5</code>, you can refer to the following ways to solve this problem:</p><ol><li>Change the communication method between APISIX and etcd from HTTPS to HTTP.</li><li>Roll back the etcd to <code>3.4.20</code>.</li><li>Clone the etcd source code and compile the <code>release-3.5</code> branch directly (this branch has fixed the problem of HTTP/2 connections, but the new version has not been released yet).</li></ol><p>The way to recompile etcd is as follows:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">git</span><span class="token plain"> checkout release-3.5</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token function" style="color:#d73a49">make</span><span class="token plain"> </span><span class="token assign-left variable" style="color:#36acaa">GOOS</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">linux </span><span class="token assign-left variable" style="color:#36acaa">GOARCH</span><span class="token operator" style="color:#393A34">=</span><span class="token plain">amd64</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>The compiled binary is in the bin directory, replace it with the etcd binary of your server environment, and then restart etcd:</p><p>For more information, please refer to:</p><ul><li><a href="https://github.com/etcd-io/etcd/issues/14185" target="_blank" rel="noopener noreferrer">when etcd node have many http long polling connections, it may cause etcd to respond slowly to http requests.</a></li><li><a href="https://github.com/apache/apisix/issues/7078" rel="noopener noreferrer">bug: when apisix starts for a while, its communication with etcd starts to time out</a></li><li><a href="https://github.com/apache/apisix/issues/7353" rel="noopener noreferrer">the prometheus metrics API is tool slow</a></li><li><a href="https://github.com/etcd-io/etcd/pull/14169" target="_blank" rel="noopener noreferrer">Support configuring <code>MaxConcurrentStreams</code> for http2</a></li></ul><p>Another solution is to switch to an experimental gRPC-based configuration synchronization. This requires setting <code>use_grpc: true</code> in the configuration file <code>conf/config.yaml</code>:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 yaml"><pre tabindex="0" class="prism-code language-yaml codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">etcd</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">use_grpc</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token boolean important" style="color:#36acaa">true</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">host</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">-</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"http://127.0.0.1:2379"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">prefix</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"/apisix"</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="why-is-the-file-logger-logging-garbled"></a>Why is the file-logger logging garbled?<a class="hash-link" href="#why-is-the-file-logger-logging-garbled" title="Direct link to heading">#</a></h2><p>If you are using the <code>file-logger</code> plugin but getting garbled logs, one possible reason is your upstream response has returned a compressed response body. You can fix this by setting the accept-encoding in the request header to not receive compressed responses using the <a href="https://apisix.apache.org/docs/apisix/plugins/proxy-rewrite/" rel="noopener noreferrer">proxy-rewirte</a> plugin:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 shell"><pre tabindex="0" class="prism-code language-shell codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#d73a49">curl</span><span class="token plain"> http://127.0.0.1:9180/apisix/admin/routes/1 </span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">-H </span><span class="token string" style="color:#e3116c">'X-API-KEY: YOUR-TOKEN'</span><span class="token plain"> -X PUT -d </span><span class="token string" style="color:#e3116c">'</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "methods":[</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "GET"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> ],</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "uri":"/test/index.html",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "plugins":{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "proxy-rewrite":{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "headers":{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "set":{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "accept-encoding":"gzip;q=0,deflate,sdch"</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> },</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "upstream":{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "type":"roundrobin",</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "nodes":{</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> "127.0.0.1:80":1</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token string" style="color:#e3116c">}'</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="how-does-apisix-configure-etcd-with-authentication"></a>How does APISIX configure ETCD with authentication?<a class="hash-link" href="#how-does-apisix-configure-etcd-with-authentication" title="Direct link to heading">#</a></h2><p>Suppose you have an ETCD cluster that enables the auth. To access this cluster, you need to configure the correct username and password for Apache APISIX in <code>conf/config.yaml</code>:</p><div class="codeBlockContainer_EiTO"><div class="codeBlockContent_X2I6 yaml"><pre tabindex="0" class="prism-code language-yaml codeBlock_UxnK thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_W6UD"><span class="token-line" style="color:#393A34"><span class="token key atrule" style="color:#00a4db">deployment</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">etcd</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">host</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">-</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">"http://127.0.0.1:2379"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">user</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> etcd_user </span><span class="token comment" style="color:#999988;font-style:italic"># username for etcd</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token key atrule" style="color:#00a4db">password</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> etcd_password </span><span class="token comment" style="color:#999988;font-style:italic"># password for etcd</span><br></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_V-PD clean-btn">Copy</button></div></div><p>For other ETCD configurations, such as expiration times, retries, and so on, you can refer to the <code>etcd</code> section in the sample configuration <code>conf/config.yaml.example</code> file.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="what-is-the-difference-between-ssls-tlsclient_cert-in-upstream-configurations-and-ssl_trusted_certificate-in-configyaml"></a>What is the difference between SSLs, <code>tls.client_cert</code> in upstream configurations, and <code>ssl_trusted_certificate</code> in <code>config.yaml</code>?<a class="hash-link" href="#what-is-the-difference-between-ssls-tlsclient_cert-in-upstream-configurations-and-ssl_trusted_certificate-in-configyaml" title="Direct link to heading">#</a></h2><p>The <code>ssls</code> is managed through the <code>/apisix/admin/ssls</code> API. It's used for managing TLS certificates. These certificates may be used during TLS handshake (between Apache APISIX and its clients). Apache APISIX uses Server Name Indication (SNI) to differentiate between certificates of different domains.</p><p>The <code>tls.client_cert</code>, <code>tls.client_key</code>, and <code>tls.client_cert_id</code> in upstream are used for mTLS communication with the upstream.</p><p>The <code>ssl_trusted_certificate</code> in <code>config.yaml</code> configures a trusted CA certificate. It is used for verifying some certificates signed by private authorities within APISIX, to avoid APISIX rejects the certificate. Note that it is not used to trust the certificates of APISIX upstream, because APISIX does not verify the legality of the upstream certificates. Therefore, even if the upstream uses an invalid TLS certificate, it can still be accessed without configuring a root certificate.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor anchor__h2 anchorWithHideOnScrollNavbar_3ly5" id="where-can-i-find-more-answers"></a>Where can I find more answers?<a class="hash-link" href="#where-can-i-find-more-answers" title="Direct link to heading">#</a></h2><p>You can find more answers on:</p><ul><li><a target="_blank" href="/docs/general/join/#join-the-slack-channel">Apache APISIX Slack Channel</a></li><li><a target="_blank" href="/docs/general/join/#subscribe-to-the-mailing-list">Ask questions on APISIX mailing list</a></li><li><a href="https://github.com/apache/apisix/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc" rel="noopener noreferrer">GitHub Issues</a> and <a href="https://github.com/apache/apisix/discussions" rel="noopener noreferrer">GitHub Discussions</a></li></ul></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="/edit#https://github.com/apache/apisix/edit/release/3.12/docs/en/latest/FAQ.md" target="_blank" rel="noreferrer noopener" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_mS5F" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_mt2f"></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages navigation"><div class="pagination-nav__item"><a class="pagination-nav__link" href="/docs/apisix/3.12/deployment-modes/"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">« Deployment modes</div></a></div><div class="pagination-nav__item pagination-nav__item--next"><a class="pagination-nav__link" href="/docs/apisix/3.12/discovery/"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Integration service discovery registry »</div></a></div></nav></div></div><div class="col col--3"><div class="tableOfContents_vrFS thin-scrollbar"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#why-do-i-need-a-new-api-gateway" class="table-of-contents__link">Why do I need a new API gateway?</a></li><li><a href="#how-does-apache-apisix-differ-from-other-api-gateways" class="table-of-contents__link">How does Apache APISIX differ from other API gateways?</a></li><li><a href="#what-is-the-performance-impact-of-using-apache-apisix" class="table-of-contents__link">What is the performance impact of using Apache APISIX?</a></li><li><a href="#which-platforms-does-apache-apisix-support" class="table-of-contents__link">Which platforms does Apache APISIX support?</a></li><li><a href="#what-does-it-mean-by-apache-apisix-is-fully-dynamic" class="table-of-contents__link">What does it mean by "Apache APISIX is fully dynamic"?</a></li><li><a href="#does-apache-apisix-have-a-user-interface" class="table-of-contents__link">Does Apache APISIX have a user interface?</a></li><li><a href="#can-i-write-my-own-plugins-for-apache-apisix" class="table-of-contents__link">Can I write my own Plugins for Apache APISIX?</a></li><li><a href="#why-does-apache-apisix-use-etcd-for-the-configuration-center" class="table-of-contents__link">Why does Apache APISIX use etcd for the configuration center?</a></li><li><a href="#when-installing-apache-apisix-dependencies-with-luarocks-why-does-it-cause-a-timeout-or-result-in-a-slow-or-unsuccessful-installation" class="table-of-contents__link">When installing Apache APISIX dependencies with LuaRocks, why does it cause a timeout or result in a slow or unsuccessful installation?</a></li><li><a href="#how-do-i-build-the-apisix-runtime-environment" class="table-of-contents__link">How do I build the APISIX-Runtime environment?</a></li><li><a href="#how-can-i-make-a-gray-release-with-apache-apisix" class="table-of-contents__link">How can I make a gray release with Apache APISIX?</a></li><li><a href="#how-do-i-redirect-http-traffic-to-https-with-apache-apisix" class="table-of-contents__link">How do I redirect HTTP traffic to HTTPS with Apache APISIX?</a></li><li><a href="#how-do-i-change-apache-apisixs-log-level" class="table-of-contents__link">How do I change Apache APISIX's log level?</a></li><li><a href="#how-do-i-reload-my-custom-plugins-for-apache-apisix" class="table-of-contents__link">How do I reload my custom Plugins for Apache APISIX?</a></li><li><a href="#how-do-i-configure-apache-apisix-to-listen-on-multiple-ports-when-handling-http-or-https-requests" class="table-of-contents__link">How do I configure Apache APISIX to listen on multiple ports when handling HTTP or HTTPS requests?</a></li><li><a href="#after-uploading-the-ssl-certificate-why-cant-the-corresponding-route-be-accessed-through-https--ip" class="table-of-contents__link">After uploading the SSL certificate, why can't the corresponding route be accessed through HTTPS + IP?</a></li><li><a href="#how-does-apache-apisix-achieve-millisecond-level-configuration-synchronization" class="table-of-contents__link">How does Apache APISIX achieve millisecond-level configuration synchronization?</a></li><li><a href="#how-do-i-customize-the-apache-apisix-instance-id" class="table-of-contents__link">How do I customize the Apache APISIX instance id?</a></li><li><a href="#why-are-there-errors-saying-failed-to-fetch-data-from-etcd-failed-to-read-etcd-dir-etcd-key-xxxxxx-in-the-errorlog" class="table-of-contents__link">Why are there errors saying "failed to fetch data from etcd, failed to read etcd dir, etcd key: xxxxxx" in the error.log?</a></li><li><a href="#how-do-i-setup-high-availability-apache-apisix-clusters" class="table-of-contents__link">How do I setup high availability Apache APISIX clusters?</a></li><li><a href="#why-does-the-make-deps-command-fail-when-installing-apache-apisix-from-source" class="table-of-contents__link">Why does the <code>make deps</code> command fail when installing Apache APISIX from source?</a></li><li><a href="#how-do-i-access-the-apisix-dashboard-through-apache-apisix-proxy" class="table-of-contents__link">How do I access the APISIX Dashboard through Apache APISIX proxy?</a></li><li><a href="#how-do-i-use-regular-expressions-regex-for-matching-uri-in-a-route" class="table-of-contents__link">How do I use regular expressions (regex) for matching <code>uri</code> in a Route?</a></li><li><a href="#does-the-upstream-node-support-configuring-a-fqdn-address" class="table-of-contents__link">Does the Upstream node support configuring a FQDN address?</a></li><li><a href="#what-is-the-x-api-key-of-the-admin-api-can-it-be-modified" class="table-of-contents__link">What is the <code>X-API-KEY</code> of the Admin API? Can it be modified?</a></li><li><a href="#how-do-i-allow-all-ips-to-access-apache-apisixs-admin-api" class="table-of-contents__link">How do I allow all IPs to access Apache APISIX's Admin API?</a></li><li><a href="#how-do-i-auto-renew-ssl-certificates-with-acmesh" class="table-of-contents__link">How do I auto renew SSL certificates with acme.sh?</a></li><li><a href="#how-do-i-strip-a-prefix-from-a-path-before-forwarding-to-upstream-in-apache-apisix" class="table-of-contents__link">How do I strip a prefix from a path before forwarding to Upstream in Apache APISIX?</a></li><li><a href="#how-do-i-fix-the-error-unable-to-get-local-issuer-certificate-in-apache-apisix" class="table-of-contents__link">How do I fix the error <code>unable to get local issuer certificate</code> in Apache APISIX?</a></li><li><a href="#how-do-i-fix-the-error-module-restyworkerevents-not-found-in-apache-apisix" class="table-of-contents__link">How do I fix the error <code>module 'resty.worker.events' not found</code> in Apache APISIX?</a></li><li><a href="#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix" class="table-of-contents__link">What is the difference between <code>plugin-metadata</code> and <code>plugin-configs</code> in Apache APISIX?</a></li><li><a href="#after-deploying-apache-apisix-how-to-detect-the-survival-of-the-apisix-data-plane" class="table-of-contents__link">After deploying Apache APISIX, how to detect the survival of the APISIX data plane?</a></li><li><a href="#what-are-the-scenarios-with-high-apisix-latency-related-to-etcd-and-how-to-fix-them" class="table-of-contents__link">What are the scenarios with high APISIX latency related to etcd and how to fix them?</a></li><li><a href="#why-is-the-file-logger-logging-garbled" class="table-of-contents__link">Why is the file-logger logging garbled?</a></li><li><a href="#how-does-apisix-configure-etcd-with-authentication" class="table-of-contents__link">How does APISIX configure ETCD with authentication?</a></li><li><a href="#what-is-the-difference-between-ssls-tlsclient_cert-in-upstream-configurations-and-ssl_trusted_certificate-in-configyaml" class="table-of-contents__link">What is the difference between SSLs, <code>tls.client_cert</code> in upstream configurations, and <code>ssl_trusted_certificate</code> in <code>config.yaml</code>?</a></li><li><a href="#where-can-i-find-more-answers" class="table-of-contents__link">Where can I find more answers?</a></li></ul></div></div></div></div></main></div></div><footer class="container_MP5Z"><div class="linksRow_iwpv"><div class="linksCol_a1ec"><div>ASF</div><ul><li class="footer__item"><a href="https://www.apache.org/" target="_blank" rel="noopener noreferrer"><span></span><span>Foundation</span></a></li><li class="footer__item"><a href="https://www.apache.org/licenses/" target="_blank" rel="noopener noreferrer"><span></span><span>License</span></a></li><li class="footer__item"><a href="https://www.apache.org/events/" target="_blank" rel="noopener noreferrer"><span></span><span>Events</span></a></li><li class="footer__item"><a href="https://www.apache.org/security/" target="_blank" rel="noopener noreferrer"><span></span><span>Security</span></a></li><li class="footer__item"><a href="https://www.apache.org/foundation/sponsorship.html" target="_blank" rel="noopener noreferrer"><span></span><span>Sponsorship</span></a></li><li class="footer__item"><a href="https://www.apache.org/foundation/thanks.html" target="_blank" rel="noopener noreferrer"><span></span><span>Thanks</span></a></li></ul></div><div class="linksCol_a1ec"><div>Community</div><ul><li class="footer__item"><a href="https://github.com/apache/apisix/issues" target="_blank" rel="noopener noreferrer"><span></span><span>GitHub</span></a></li><li class="footer__item"><a href="/docs/general/join/"><span></span><span>Slack</span></a></li><li class="footer__item"><a href="https://twitter.com/ApacheAPISIX" target="_blank" rel="noopener noreferrer"><span></span><span>Twitter</span></a></li><li class="footer__item"><a href="https://www.youtube.com/channel/UCgPD18cMhOg5rmPVnQhAC8g" target="_blank" rel="noopener noreferrer"><span></span><span>YouTube</span></a></li></ul></div><div class="linksCol_a1ec"><div>More</div><ul><li class="footer__item"><a target="_parent" href="/blog/"><span></span><span>Blog</span></a></li><li class="footer__item"><a target="_parent" href="/showcase/"><span></span><span>Showcase</span></a></li><li class="footer__item"><a target="_parent" href="/plugins/"><span></span><span>Plugin Hub</span></a></li><li class="footer__item"><a href="https://github.com/apache/apisix/milestones" target="_parent" rel="noopener noreferrer"><span></span><span>Roadmap</span></a></li></ul></div></div><div class="copyright_ZfFh"><a href="https://www.apache.org/" target="_blank" rel="noopener noreferrer"><span style="display:inline-block;width:231.25px;height:40px"></span></a><div>Copyright © 2019-2025 The Apache Software Foundation. Apache APISIX, APISIX®, Apache, the Apache feather logo, and the Apache APISIX project logo are either registered trademarks or trademarks of the Apache Software Foundation.</div></div></footer></div> |
| <script src="https://apisix-website-static.apiseven.com/assets/js/runtime~main.06b57428.js"></script> |
| <script src="https://apisix-website-static.apiseven.com/assets/js/main.3aedbf26.js"></script> |
| </body> |
| </html> |
