diff --git a/docs/_ext/powershell_lexer.py b/docs/_ext/powershell_lexer.py new file mode 100644 index 0000000000000..74a077708245d --- /dev/null +++ b/docs/_ext/powershell_lexer.py @@ -0,0 +1,5 @@ +from pygments.lexers import get_lexer_by_name + + +def setup(app): + app.add_lexer('powershell', get_lexer_by_name('powershell')) diff --git a/docs/conf.py b/docs/conf.py index d4fa5605f588f..f3eebfd4fb1ba 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -72,7 +72,7 @@ def setup(app): extensions = [ 'sphinxcontrib.httpdomain', 'sphinx.ext.extlinks', 'sphinx.ext.ifconfig', 'sphinx_tabs.tabs', - 'sphinx_copybutton', 'validating_code_block', 'sphinxext.rediraffe' + 'sphinx_copybutton', 'validating_code_block', 'sphinxext.rediraffe', 'powershell_lexer' ] extlinks = { 'repo': ('https://github.com/envoyproxy/envoy/blob/{}/%s'.format(blob_sha), ''), @@ -81,9 +81,11 @@ def setup(app): # Setup global substitutions if 'pre-release' in release_level: - substitutions = [('|envoy_docker_image|', 'envoy-dev:{}'.format(blob_sha))] + substitutions = [('|envoy_docker_image|', 'envoy-dev:{}'.format(blob_sha)), + ('|envoy_windows_docker_image|', 'envoy-windows-dev:{}'.format(blob_sha))] else: - substitutions = [('|envoy_docker_image|', 'envoy:{}'.format(blob_sha))] + substitutions = [('|envoy_docker_image|', 'envoy:{}'.format(blob_sha)), + ('|envoy_windows_docker_image|', 'envoy-windows:{}'.format(blob_sha))] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/root/start/quick-start/run-envoy.rst b/docs/root/start/quick-start/run-envoy.rst index 8459b0a12db78..2cf0fe7d14bc9 100644 --- a/docs/root/start/quick-start/run-envoy.rst +++ b/docs/root/start/quick-start/run-envoy.rst @@ -23,7 +23,7 @@ Once you have :ref:`installed Envoy `, you can check the version inform $ envoy --version ... - .. tab:: Docker + .. tab:: Docker (Linux Image) .. substitution-code-block:: console @@ -31,6 +31,14 @@ Once you have :ref:`installed Envoy `, you can check the version inform envoyproxy/|envoy_docker_image| \ --version ... + .. tab:: Docker (Windows Image) + + .. substitution-code-block:: powershell + + PS> docker run --rm + 'envoyproxy/|envoy_windows_docker_image|' + --version + ... .. _start_quick_start_help: @@ -49,7 +57,7 @@ flag: $ envoy --help ... - .. tab:: Docker + .. tab:: Docker (Linux Image) .. substitution-code-block:: console @@ -58,6 +66,15 @@ flag: --help ... + .. tab:: Docker (Windows Image) + + .. substitution-code-block:: powershell + + PS> docker run --rm + 'envoyproxy/|envoy_windows_docker_image|' + --help + ... + .. _start_quick_start_config: Run Envoy with the demo configuration @@ -77,7 +94,7 @@ The ``-c`` or ``--config-path`` flag tells Envoy the path to its initial configu $ envoy -c envoy-demo.yaml ... - .. tab:: Docker + .. tab:: Docker (Linux Image) You can start the Envoy Docker image without specifying a configuration file, and it will use the demo config by default. @@ -104,52 +121,33 @@ The ``-c`` or ``--config-path`` flag tells Envoy the path to its initial configu -c /envoy-custom.yaml ... - .. tab:: Windows Service + .. tab:: Docker (Windows Image) - .. note:: + You can start the Envoy Docker image without specifying a configuration file, and + it will use the demo config by default. - This feature is still in Experimental state. + .. substitution-code-block:: powershell - You can start Envoy as Windows Service that is managed under `Windows Service Control Manager `_. + PS> docker run --rm -it + -p '9901:9901' + -p '10000:10000' + 'envoyproxy/|envoy_windows_docker_image|' + ... - First, you need to create the service. Assuming you have a custom configuration in the current directory named ``envoy-custom.yaml``. After you create the service you - can start it. + To specify a custom configuration you can mount the config into the container, and specify the path with ``-c``. - From an **administrator** prompt run the following commands (note that you need replace C:\EnvoyProxy\ with the path to the envoy.exe binary and the config file): + Assuming you have a custom configuration in the current directory named ``envoy-custom.yaml``, from PowerShell run: - .. substitution-code-block:: console + .. substitution-code-block:: powershell - > sc create EnvoyProxy binpath="C:\EnvoyProxy\envoy.exe --config-path C:\EnvoyProxy\envoy-demo.yaml" start=auto depend=Tcpip/Afd - [SC] CreateService SUCCESS - > sc start EnvoyProxy - SERVICE_NAME: envoyproxy - TYPE : 10 WIN32_OWN_PROCESS - STATE : 2 START_PENDING - (NOT_STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN) - WIN32_EXIT_CODE : 0 (0x0) - SERVICE_EXIT_CODE : 0 (0x0) - CHECKPOINT : 0x0 - WAIT_HINT : 0x7d0 - PID : 3924 - FLAGS : - > sc query EnvoyProxy - SERVICE_NAME: envoyproxy - TYPE : 10 WIN32_OWN_PROCESS - STATE : 4 RUNNING - (STOPPABLE, NOT_PAUSABLE, ACCEPTS_SHUTDOWN) - WIN32_EXIT_CODE : 0 (0x0) - SERVICE_EXIT_CODE : 0 (0x0) - CHECKPOINT : 0x0 - WAIT_HINT : 0x0 + PS> docker run --rm -it + -v "$PWD\:`"C:\envoy-configs`"" + -p '9901:9901' + -p '10000:10000' + 'envoyproxy/|envoy_windows_docker_image|' + -c 'C:\envoy-configs\envoy-custom.yaml' ... - Use `sc.exe `_ to configure the service startup and error handling. - - .. tip:: - - The output of ``sc query envoyproxy`` contains the exit code of Envoy Proxy. In case the arguments are invalid we set it to ``E_INVALIDARG``. For more information - Envoy is reporting startup failures with error messages on Windows Event Viewer. - Check Envoy is proxying on http://localhost:10000. .. code-block:: console @@ -193,12 +191,21 @@ Next, start the Envoy server using the override configuration: .. tab:: System + On Linux/Mac: run: + .. code-block:: console $ envoy -c envoy-demo.yaml --config-yaml "$(cat envoy-override.yaml)" ... - .. tab:: Docker + On Windows run: + + .. code-block:: powershell + + $ envoy -c envoy-demo.yaml --config-yaml "$(Get-Content -Raw envoy-override.yaml)" + ... + + .. tab:: Docker (Linux Image) .. substitution-code-block:: console @@ -210,6 +217,18 @@ Next, start the Envoy server using the override configuration: --config-yaml "$(cat envoy-override.yaml)" ... + .. tab:: Docker (Windows Image) + + .. substitution-code-block:: powershell + + PS> docker run --rm -it + -p '9902:9902' + -p '10000:10000' + 'envoyproxy/|envoy_windows_docker_image|' + -c 'C:\ProgramData\envoy.yaml' + --config-yaml "$(Get-Content -Raw envoy-override.yaml)" + ... + The Envoy admin interface should now be available on http://localhost:9902. .. code-block:: console @@ -260,7 +279,7 @@ For invalid configuration the process will print the errors and exit with ``1``. [2020-11-08 12:36:06.549][11][info][config] [source/server/configuration_impl.cc:121] loading stats sink configuration configuration 'my-envoy-config.yaml' OK - .. tab:: Docker + .. tab:: Docker (Linux Image) .. substitution-code-block:: console @@ -283,6 +302,20 @@ For invalid configuration the process will print the errors and exit with ``1``. [2020-11-08 12:36:06.549][11][info][config] [source/server/configuration_impl.cc:121] loading stats sink configuration configuration 'my-envoy-config.yaml' OK + .. tab:: Docker (Windows Image) + + .. substitution-code-block:: powershell + + PS> docker run --rm -it + -v "$PWD\:`"C:\envoy-configs`"" + -p '9901:9901' + -p '10000:10000' + 'envoyproxy/|envoy_windows_docker_image|' + --mode validate + -c 'C:\envoy-configs\my-envoy-config.yaml' + + configuration 'my-envoy-config.yaml' OK + Envoy logging ------------- @@ -299,7 +332,7 @@ This can be overridden using :option:`--log-path`. $ mkdir logs $ envoy -c envoy-demo.yaml --log-path logs/custom.log - .. tab:: Docker + .. tab:: Docker (Linux Image) .. substitution-code-block:: console @@ -312,6 +345,24 @@ This can be overridden using :option:`--log-path`. -c /etc/envoy/envoy.yaml \ --log-path logs/custom.log + .. tab:: Docker (Windows Image) + + .. substitution-code-block:: powershell + + PS> mkdir logs + PS> docker run --rm -it + -p '10000:10000' + -v "$PWD\logs\:`"C:\logs`"" + 'envoyproxy/|envoy_windows_docker_image|' + -c 'C:\ProgramData\envoy.yaml' + --log-path 'C:\logs\custom.log' + + .. note:: + + Envoy on a Windows system Envoy will output to ``CON`` by default. + + This can also be used as a logging path when configuring logging. + :ref:`Access log ` paths can be set for the :ref:`admin interface `, and for configured :ref:`listeners `. @@ -338,12 +389,6 @@ Some Envoy :ref:`filters and extensions ` may also have additiona Envoy can be configured to log to :ref:`different formats `, and to :ref:`different outputs ` in addition to files and ``stdout/err``. -.. note:: - - If you are running Envoy on a Windows system Envoy will output to ``CON`` by default. - - This can also be used as a logging path when configuring logging. - Debugging Envoy --------------- @@ -375,7 +420,7 @@ which are set to ``debug`` and ``trace`` respectively. $ envoy -c envoy-demo.yaml -l off --component-log-level upstream:debug,connection:trace ... - .. tab:: Docker + .. tab:: Docker (Linux Image) .. substitution-code-block:: console @@ -388,6 +433,19 @@ which are set to ``debug`` and ``trace`` respectively. --component-log-level upstream:debug,connection:trace ... + .. tab:: Docker (Windows Image) + + .. substitution-code-block:: powershell + + PS> mkdir logs + PS> docker run --rm -it + -p '10000:10000' + envoyproxy/|envoy_windws_docker_image| + -c 'C:\ProgramData\envoy.yaml' + -l off + --component-log-level 'upstream:debug,connection:trace' + ... + .. tip:: See ``ALL_LOGGER_IDS`` in :repo:`logger.h ` for a list of components.