Skip to content

Win32 docs for run-envoy.rst section #15813

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mattklein123 merged 16 commits into from
Apr 15, 2021
Merged

Win32 docs for run-envoy.rst section #15813

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
7f01f38
Add Windows container tabs on run-envoy
Apr 1, 2021
2b01b41
format python
Apr 1, 2021
424e345
add new line at the end
Apr 1, 2021
eb93dde
remove unused imports
Apr 1, 2021
4e1e7c4
py format
Apr 1, 2021
714590c
Merge remote-tracking branch 'upstream/main' into win32DocsRunEnvoy
Apr 1, 2021
3b0066a
fix trailing whitespace
Apr 1, 2021
aa042cd
use default image when possible
Apr 1, 2021
2216c40
Unblock CI
Apr 6, 2021
96aa0b0
PR comments
Apr 13, 2021
bf59fc9
change the names in the tabs
Apr 14, 2021
59dd39a
make it plural
Apr 14, 2021
fdc1229
another iteration
Apr 14, 2021
c8ac4b7
change the tab titles
Apr 14, 2021
4942909
Remove windows service
Apr 14, 2021
f5641b6
Merge remote-tracking branch 'upstream/main' into win32DocsRunEnvoy
Apr 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/_ext/powershell_lexer.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
from pygments.lexers import get_lexer_by_name


def setup(app):
app.add_lexer('powershell', get_lexer_by_name('powershell'))
8 changes: 5 additions & 3 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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), ''),
Expand All @@ -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']
Expand Down
158 changes: 108 additions & 50 deletions docs/root/start/quick-start/run-envoy.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,14 +23,22 @@ Once you have :ref:`installed Envoy <install>`, you can check the version inform
$ envoy --version
...

.. tab:: Docker
.. tab:: Docker (Linux Image)

.. substitution-code-block:: console

$ docker run --rm \
envoyproxy/|envoy_docker_image| \
--version
...
.. tab:: Docker (Windows Image)

Copy link
Copy Markdown
Member

@phlax phlax Apr 14, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

like here - i would add:

These are instructions for using the Windows Docker image - if you wish to use the Linux image on a Windows host machine please see the "Docker (Linux)" instructions

Copy link
Copy Markdown
Member

@phlax phlax Apr 14, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this comment placed here is what i think would work best

.. substitution-code-block:: powershell

PS> docker run --rm
'envoyproxy/|envoy_windows_docker_image|'
--version
...

.. _start_quick_start_help:

Expand All @@ -49,7 +57,7 @@ flag:
$ envoy --help
...

.. tab:: Docker
.. tab:: Docker (Linux Image)

.. substitution-code-block:: console

Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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 <https://docs.microsoft.com/en-us/windows/win32/services/using-services/>`_.
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 <https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/sc-create/>`_ 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
Expand Down Expand Up @@ -186,12 +184,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

Expand All @@ -203,6 +210,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
Expand Down Expand Up @@ -253,7 +272,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

Expand All @@ -276,6 +295,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
-------------

Expand All @@ -292,7 +325,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

Expand All @@ -305,6 +338,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 <arch_overview_access_logs>` paths can be set for the
:ref:`admin interface <start_quick_start_admin>`, and for configured
:ref:`listeners <envoy_v3_api_file_envoy/config/listener/v3/listener.proto>`.
Expand All @@ -331,12 +382,6 @@ Some Envoy :ref:`filters and extensions <api-v3_config>` may also have additiona
Envoy can be configured to log to :ref:`different formats <config_access_log>`, and to
:ref:`different outputs <api-v3_config_accesslog>` 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
---------------

Expand Down Expand Up @@ -368,7 +413,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

Expand All @@ -381,6 +426,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 </source/common/common/logger.h#L29>` for a list of components.