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 12 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))]
Comment thread
davinci26 marked this conversation as resolved.
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
136 changes: 123 additions & 13 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 @@ -7,6 +7,12 @@ Run Envoy
The following instructions walk through starting Envoy as a system daemon or using
the Envoy Docker image.

.. note::

For Linux containers follow the instructions in Docker (Linux) tab and for Windows containers

@phlax phlax Apr 14, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

personally i think put this in the actual tabs - dont assume that someone reads the whole doc - also i think it needs to be clearer...

@davinci26 davinci26 Apr 14, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Isnt this repetitive to have this in every tab?

@phlax phlax Apr 14, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

i dont think so - and personally i often ctrl-f or otherwise skip to the section im interested in so i would put it in each tab

@davinci26 davinci26 Apr 14, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Do you think that a green note is distracting away someone who is reading the windows doc tab?

@phlax phlax Apr 14, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

perhaps dont use an actual .. note: - just some text would do imho

@davinci26 davinci26 Apr 14, 2021 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Shouldn't we just use the title Docker (Windows Container) and Docker (Linux Container) and skip the sentence. We are saving 10 characters from the tab title and then we add two sentences in each tab.

@phlax phlax Apr 14, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

i dont think so - pretty sure this was the conv we already had - not sure what more i can add (other than i also think that image is more appropriate in this context)

follow the Docker (Windows) instructions.


.. _start_quick_start_version:

Check your Envoy version
Expand All @@ -23,14 +29,22 @@ Once you have :ref:`installed Envoy <install>`, you can check the version inform
$ envoy --version
...

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

.. substitution-code-block:: console

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

@phlax phlax Apr 14, 2021 •
edited
Loading

Copy link
Copy Markdown
Member

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

@phlax phlax Apr 14, 2021

Copy link
Copy Markdown
Member

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
Comment thread
davinci26 marked this conversation as resolved.
Outdated

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

.. _start_quick_start_help:

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

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

.. substitution-code-block:: console

Expand All @@ -58,6 +72,15 @@ flag:
--help
...

.. tab:: Docker (Windows)

.. 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 +100,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)

You can start the Envoy Docker image without specifying a configuration file, and
it will use the demo config by default.
Expand All @@ -104,6 +127,33 @@ The ``-c`` or ``--config-path`` flag tells Envoy the path to its initial configu
-c /envoy-custom.yaml
...

.. tab:: Docker (Windows)

You can start the Envoy Docker image without specifying a configuration file, and
it will use the demo config by default.

.. substitution-code-block:: PowerShell

PS> docker run --rm -it
-p '9901:9901'
Comment thread
davinci26 marked this conversation as resolved.
-p '10000:10000'
'envoyproxy/|envoy_windows_docker_image|'
...

To specify a custom configuration you can mount the config into the container, and specify the path with ``-c``.

Assuming you have a custom configuration in the current directory named ``envoy-custom.yaml``, from PowerShell run:

.. 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|'
-c 'C:\envoy-configs\envoy-custom.yaml'
...

.. tab:: Windows Service

.. note::
Expand Down Expand Up @@ -192,12 +242,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)

.. substitution-code-block:: console

Expand All @@ -209,6 +268,18 @@ Next, start the Envoy server using the override configuration:
--config-yaml "$(cat envoy-override.yaml)"
...

.. tab:: Docker (Windows)

.. 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 @@ -259,7 +330,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)

.. substitution-code-block:: console

Expand All @@ -282,6 +353,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)

.. substitution-code-block:: PowerShell

PS> docker run --rm -it
-v "$PWD\:`"C:\envoy-configs`""
Comment thread
davinci26 marked this conversation as resolved.
Outdated
-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
Comment thread
davinci26 marked this conversation as resolved.

Envoy logging
-------------

Expand All @@ -298,7 +383,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)

.. substitution-code-block:: console

Expand All @@ -311,6 +396,24 @@ This can be overridden using :option:`--log-path`.
-c /etc/envoy/envoy.yaml \
--log-path logs/custom.log

.. tab:: Docker (Windows)

.. 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 @@ -337,12 +440,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 @@ -374,7 +471,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)

.. substitution-code-block:: console

Expand All @@ -387,6 +484,19 @@ which are set to ``debug`` and ``trace`` respectively.
--component-log-level upstream:debug,connection:trace
...

.. tab:: Docker (Windows)

.. 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.