mirror of
https://github.com/openziti/zrok.git
synced 2025-02-17 10:40:57 +01:00
17 lines
25 KiB
HTML
17 lines
25 KiB
HTML
<!doctype html>
|
||
<html lang="en" dir="ltr" class="docs-wrapper docs-doc-page docs-version-current plugin-docs plugin-id-default docs-doc-id-overview">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="generator" content="Docusaurus v2.2.0">
|
||
<title data-rh="true">What is `zrok` | Zrok</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://zrok.io/docs/overview"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="What is `zrok` | Zrok"><meta data-rh="true" name="description" content="Overview"><meta data-rh="true" property="og:description" content="Overview"><link data-rh="true" rel="icon" href="/img/space-ziggy.png"><link data-rh="true" rel="canonical" href="https://zrok.io/docs/overview"><link data-rh="true" rel="alternate" href="https://zrok.io/docs/overview" hreflang="en"><link data-rh="true" rel="alternate" href="https://zrok.io/docs/overview" hreflang="x-default"><link rel="stylesheet" href="/assets/css/styles.e8494040.css">
|
||
<link rel="preload" href="/assets/js/runtime~main.955942a2.js" as="script">
|
||
<link rel="preload" href="/assets/js/main.e6a888d1.js" as="script">
|
||
</head>
|
||
<body class="navigation-with-keyboard">
|
||
<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:"dark")}()</script><div id="__docusaurus">
|
||
<div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#docusaurus_skipToContent_fallback">Skip to main content</a></div><nav class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><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 class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/space-ziggy.png" alt="Ziggy Goes to Space" class="themedImage_ToTc themedImage--light_HNdA"><img src="/img/space-ziggy.png" alt="Ziggy Goes to Space" class="themedImage_ToTc themedImage--dark_i4oU"></div><b class="navbar__title text--truncate">zrok</b></a></div><div class="navbar__items navbar__items--right"><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs/overview">What is zrok?</a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs/overview">Docs</a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs/downloads">Downloads</a><a href="https://github.com/openziti/zrok" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><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></a><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="Switch between dark and light mode (currently dark mode)" aria-label="Switch between dark and light mode (currently dark mode)" aria-live="polite"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" class="darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg></button></div><div class="searchBox_ZlJk"></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_z2l0 docsWrapper_BCFX"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docPage__5DB"><aside class="theme-doc-sidebar-container docSidebarContainer_b6E3"><div class="sidebar_njMd"><nav class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" href="/docs/overview">What is zrok</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/docs/category/getting-started">Getting Started</a><button aria-label="Toggle the collapsible sidebar category 'Getting Started'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/docs/category/sharing">Sharing</a><button aria-label="Toggle the collapsible sidebar category 'Sharing'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/docs/category/guides">Guides</a><button aria-label="Toggle the collapsible sidebar category 'Guides'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/docs/category/network">Network</a><button aria-label="Toggle the collapsible sidebar category 'Network'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/downloads">Downloads</a></li></ul></nav></div></aside><main class="docMainContainer_gTbr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_OVgt"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">What is zrok</span><meta itemprop="position" content="1"></li></ul></nav><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><h1>What is <code>zrok</code></h1><h2 class="anchor anchorWithStickyNavbar_LWe7" id="overview">Overview<a class="hash-link" href="#overview" title="Direct link to heading"></a></h2><p><code>zrok</code> is a super-lightweight tool for providing on-demand access to dark, unreachable resources.
|
||
The super-power of <code>zrok</code> is providing a single-step solution to creating ephemeral network connectivity. From an end-user perspective, <code>zrok</code> is a tool packaged as a single executable, which can be used as a "shim" to quickly create public endpoints for dark resources.</p><p><code>zrok</code> is also a service (which can be self-hosted) and runs on top of any OpenZiti network. The service provides one or more listening endpoints (typically on the public internet), that are designed to dynamically expose endpoints (HTTP(S)-only, as of v0.1.x), as requested by the end-user <code>zrok</code> tooling.</p><p><code>zrok</code> listening endpoints, and <code>zrok</code> terminating endpoints are typically used together to create the streamlined, ephemeral connectivity solution for dark services. But listening endpoints and the terminating endpoints can be used orthogonally, interoperating with other OpenZiti SDK clients.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="the-primary-use-case">The Primary Use Case<a class="hash-link" href="#the-primary-use-case" title="Direct link to heading"></a></h3><p>The primary use case for <code>zrok</code> is exposing dark resources across the public internet, for a multiplicity of reasons. Consider a developer, who is building a web application and wants to share work in progress with third parties for review. The developer already has signed up for a <code>zrok</code> account and has been issued a secret token.</p><p>The developer will have enabled <code>zrok</code> capabilities for their shell environment using the <code>zrok enable</code> command:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok enable <secret-token></span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>After enabling their environment, the developer can quickly create a publicly available URL for their application like this:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">$ zrok http http://localhost:3000</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p><code>zrok</code> will then give them a public URL, like this:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">http://d9121e7cdfd2dd2f.zrok.io/</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>This URL can be shared with anyone, anywhere, allowing access to the developer's application as long as the developer is running the <code>zrok http</code> command. Simply ending that process will destroy all of the public access, and clean up the associated resources in the underlying OpenZiti environment.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="how-does-zrok-work">How Does <code>zrok</code> Work?<a class="hash-link" href="#how-does-zrok-work" title="Direct link to heading"></a></h2><p>At a high level, the <code>zrok</code> stack looks like this:</p><p><img loading="lazy" alt="zrok v0.1 overview" src="data:image/png;base64,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" width="150" height="150" class="img_ev3q"></p><p>Let's discuss a couple of the flows through the above use case and talk about what's happening.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="the-zrok-enable-flow">The <code>zrok enable</code> Flow<a class="hash-link" href="#the-zrok-enable-flow" title="Direct link to heading"></a></h3><p>When a new <code>zrok</code> user signs up for an account, they are issued a "secret token". This secret token is used to enable shell access to <code>zrok http</code> from the command line.</p><p>When the user runs <code>zrok enable</code> from their shell, here's what happens:</p><ol><li>The <code>zrok enable</code> client reaches out with an enable request to the <code>zrok</code> controller.</li><li>The <code>zrok</code> controller creates a new OpenZiti identity for the environment and enrolls it.</li><li>The <code>zrok</code> controller creates an edge router policy associating the new OpenZiti identity with <code>#all</code> edge routers.</li><li>The <code>zrok</code> controller returns the entire SDK configuration back to the <code>zrok enable</code> client.</li><li>The <code>zrok enable</code> client then stores the OpenZiti identity along with a few other housekeeping details in the user's <code>~/.zrok</code> folder (we refer to this as <code>zrokdir</code>, conceptually in the code).</li><li>With the OpenZiti identity and configuration details stored in the user's <code>zrokdir</code>, the user is then able to create any number of binding endpoints using the <code>zrok http</code> command.</li></ol><h3 class="anchor anchorWithStickyNavbar_LWe7" id="the-zrok-http-flow">The <code>zrok http</code> Flow<a class="hash-link" href="#the-zrok-http-flow" title="Direct link to heading"></a></h3><p>When a <code>zrok</code> user issues a <code>zrok http</code> command for an endpoint, here's what happens:</p><ol><li>The <code>zrok http</code> client gathers the necessary identity details from the <code>zrokdir</code> (this was all staged during <code>zrok enable</code>).</li><li>The <code>zrok http</code> client reaches out to the <code>zrok</code> controller with an authenticated <code>tunnel</code> request, asking to have a new endpoint binding created.</li><li>The <code>zrok</code> controller allocates a new "service name" for the binding.</li><li>The <code>zrok</code> controller creates a <code>zrok.proxy.v1</code> configuration describing the user's requested authentication details (currently: <code>none</code> or <code>basic</code>).</li><li>The <code>zrok</code> controller creates a new service, associating the service with the configuration.</li><li>The <code>zrok</code> controller creates a bind service policy for the user's environment identity and the newly created OpenZiti service.</li><li>The <code>zrok</code> controller creates a dial service policy allowing the configured listening endpoints (ingress proxies) to dial the newly created service.</li><li>The <code>zrok</code> controller creates a service edge router policy associating the newly created service with <code>#all</code> edge routers.</li><li>The URL for the new <code>zrok</code> service is constructed and returned to the <code>zrok http</code> client.</li><li>The <code>zrok http</code> client then binds the OpenZiti service with an SDK client, and begins reverse-proxying traffic received from OpenZiti across to the dark service.</li></ol><p>When the user terminates the <code>zrok http</code> client, these resources are removed from the OpenZiti network.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="zrok-proxy-and-http-clients"><code>zrok proxy</code> and HTTP Clients<a class="hash-link" href="#zrok-proxy-and-http-clients" title="Direct link to heading"></a></h3><p>When <code>zrok http</code> exposes a service and returns a URL, that URL is designed to be sent to a <code>zrok</code> listening endpoint (<code>zrok proxy</code>, currently). The <code>zrok proxy</code> is a stateless SDK client with an HTTP(S) listener exposed to the public internet.</p><p>When an HTTP request arrives as the <code>zrok proxy</code> listener, this happens:</p><ol><li>The <code>zrok proxy</code> parses the <code>Host</code> header provided by the client, extracting the <code>zrok</code> service name from the URL.</li><li>The service is refreshed (if necessary) and retrieved. The <code>zrok.proxy.v1</code> configuration details are retrieved.</li><li>The <code>zrok.proxy.v1</code> configuration is used to do authentication processing. If authentication is required, such a response is returned to the client.</li><li>The <code>zrok proxy</code> then dials the OpenZiti service, and the dialed service is used to reverse proxy the request from the end user across OpenZiti to the binding endpoint, and then dark service.</li></ol><p>The <code>zrok proxy</code> does not require any communication with the <code>zrok</code> controller, and is stateless. They can be pooled behind a load balancer. It is currently a goal is to maintain this lightweight nature.</p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="https://github.com/openziti/zrok/tree/main/../docs/overview.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_Z9Sw" 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_vwxv"></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages navigation"><a class="pagination-nav__link pagination-nav__link--next" href="/docs/category/getting-started"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Getting Started</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#overview" class="table-of-contents__link toc-highlight">Overview</a><ul><li><a href="#the-primary-use-case" class="table-of-contents__link toc-highlight">The Primary Use Case</a></li></ul></li><li><a href="#how-does-zrok-work" class="table-of-contents__link toc-highlight">How Does <code>zrok</code> Work?</a><ul><li><a href="#the-zrok-enable-flow" class="table-of-contents__link toc-highlight">The <code>zrok enable</code> Flow</a></li><li><a href="#the-zrok-http-flow" class="table-of-contents__link toc-highlight">The <code>zrok http</code> Flow</a></li><li><a href="#zrok-proxy-and-http-clients" class="table-of-contents__link toc-highlight"><code>zrok proxy</code> and HTTP Clients</a></li></ul></li></ul></div></div></div></div></main></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="footer__bottom text--center"><div class="footer__copyright">Copyright © 2023 NetFoundry Inc. Built with Docusaurus.</div></div></div></footer></div>
|
||
<script src="/assets/js/runtime~main.955942a2.js"></script>
|
||
<script src="/assets/js/main.e6a888d1.js"></script>
|
||
</body>
|
||
</html> |