Skip to content

Add documentation for creating nitlsconfig gRPC channels #2210

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

Open
alexdubois-ni wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add documentation for creating nitlsconfig gRPC channels #2210

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
59 changes: 53 additions & 6 deletions build/templates/grpc_session_options.rst.mako
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,53 @@ Support for using ${driver_name} over gRPC



Creating a gRPC channel
-----------------------

Using ${driver_name} over gRPC requires the ``grpc`` extra::

$ python -m pip install ${module_name}[grpc]

Every ${driver_name} gRPC session is created from a ``grpc.Channel`` that you build and pass to
:py:class:`${module_name}.GrpcSessionOptions`. You own the channel, not the session, so you must
close it after the last session using it is closed.

The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is
``create_grpc_device_channel`` from the `nitlsconfig <https://pypi.org/project/nitlsconfig/>`_ package,
which the ``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed
with the ${driver_name} runtime and by default will attempt to build an encrypted gRPC channel using mTLS.

Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a
certificate exchange with the remote system.
See `Managing mTLS <https://www.ni.com/docs/en-US/bundle/hardwaremanager/page/mtls-manage.html>`_ for
additional information.

For example::

import ${module_name}
import nitlsconfig

with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel:
options = ${module_name}.GrpcSessionOptions(channel, '')
with ${module_name}.Session('dev1', grpc_options=options) as session:
# Calls to session over the encrypted channel

.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel``
produce an insecure channel.

.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel
arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel
arguments cannot be changed after the channel is built, so they must be supplied here.

.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its
TLS settings from nitlsconfig. See
`Bind Address Support <https://github.com/ni/grpc-device#bind-address-support>`_ and
`NI TLS Config Integration <https://github.com/ni/grpc-device#ni-tls-config-integration>`_ for details.

You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel``
if you need full control over how credentials are supplied.


SessionInitializationBehavior
-----------------------------

Expand Down Expand Up @@ -62,17 +109,17 @@ GrpcSessionOptions


:param grpc_channel:


Specifies the channel to the NI gRPC Device Server.



:type grpc_channel: grpc.Channel


:param session_name:


User-specified name that identifies the driver session on the NI gRPC Device Server.

Expand All @@ -81,18 +128,18 @@ GrpcSessionOptions
You can use an empty string if you want to always initialize a new session on the server.
To attach to an existing session, you must specify the session name it was initialized with.



:type session_name: str


:param initialization_behavior:


Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired.

The driver session exists on the NI gRPC Device Server.



:type initialization_behavior: :py:data:`${module_name}.SessionInitializationBehavior`
59 changes: 53 additions & 6 deletions docs/nidcpower/grpc_session_options.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,53 @@ Support for using NI-DCPower over gRPC



Creating a gRPC channel
-----------------------

Using NI-DCPower over gRPC requires the ``grpc`` extra::

$ python -m pip install nidcpower[grpc]

Every NI-DCPower gRPC session is created from a ``grpc.Channel`` that you build and pass to
:py:class:`nidcpower.GrpcSessionOptions`. You own the channel, not the session, so you must
close it after the last session using it is closed.

The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is
``create_grpc_device_channel`` from the `nitlsconfig <https://pypi.org/project/nitlsconfig/>`_ package,
which the ``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed
with the NI-DCPower runtime and by default will attempt to build an encrypted gRPC channel using mTLS.

Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a
certificate exchange with the remote system.
See `Managing mTLS <https://www.ni.com/docs/en-US/bundle/hardwaremanager/page/mtls-manage.html>`_ for
additional information.

For example::

import nidcpower
import nitlsconfig

with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel:
options = nidcpower.GrpcSessionOptions(channel, '')
with nidcpower.Session('dev1', grpc_options=options) as session:
# Calls to session over the encrypted channel

.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel``
produce an insecure channel.

.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel
arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel
arguments cannot be changed after the channel is built, so they must be supplied here.

.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its
TLS settings from nitlsconfig. See
`Bind Address Support <https://github.com/ni/grpc-device#bind-address-support>`_ and
`NI TLS Config Integration <https://github.com/ni/grpc-device#ni-tls-config-integration>`_ for details.

You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel``
if you need full control over how credentials are supplied.


SessionInitializationBehavior
-----------------------------

Expand Down Expand Up @@ -55,17 +102,17 @@ GrpcSessionOptions


:param grpc_channel:


Specifies the channel to the NI gRPC Device Server.



:type grpc_channel: grpc.Channel


:param session_name:


User-specified name that identifies the driver session on the NI gRPC Device Server.

Expand All @@ -74,18 +121,18 @@ GrpcSessionOptions
You can use an empty string if you want to always initialize a new session on the server.
To attach to an existing session, you must specify the session name it was initialized with.



:type session_name: str


:param initialization_behavior:


Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired.

The driver session exists on the NI gRPC Device Server.



:type initialization_behavior: :py:data:`nidcpower.SessionInitializationBehavior`
59 changes: 53 additions & 6 deletions docs/nidigital/grpc_session_options.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,53 @@ Support for using NI-Digital Pattern Driver over gRPC



Creating a gRPC channel
-----------------------

Using NI-Digital Pattern Driver over gRPC requires the ``grpc`` extra::

$ python -m pip install nidigital[grpc]

Every NI-Digital Pattern Driver gRPC session is created from a ``grpc.Channel`` that you build and pass to
:py:class:`nidigital.GrpcSessionOptions`. You own the channel, not the session, so you must
close it after the last session using it is closed.

The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is
``create_grpc_device_channel`` from the `nitlsconfig <https://pypi.org/project/nitlsconfig/>`_ package,
which the ``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed
with the NI-Digital Pattern Driver runtime and by default will attempt to build an encrypted gRPC channel using mTLS.

Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a
certificate exchange with the remote system.
See `Managing mTLS <https://www.ni.com/docs/en-US/bundle/hardwaremanager/page/mtls-manage.html>`_ for
additional information.

For example::

import nidigital
import nitlsconfig

with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel:
options = nidigital.GrpcSessionOptions(channel, '')
with nidigital.Session('dev1', grpc_options=options) as session:
# Calls to session over the encrypted channel

.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel``
produce an insecure channel.

.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel
arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel
arguments cannot be changed after the channel is built, so they must be supplied here.

.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its
TLS settings from nitlsconfig. See
`Bind Address Support <https://github.com/ni/grpc-device#bind-address-support>`_ and
`NI TLS Config Integration <https://github.com/ni/grpc-device#ni-tls-config-integration>`_ for details.

You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel``
if you need full control over how credentials are supplied.


SessionInitializationBehavior
-----------------------------

Expand Down Expand Up @@ -55,17 +102,17 @@ GrpcSessionOptions


:param grpc_channel:


Specifies the channel to the NI gRPC Device Server.



:type grpc_channel: grpc.Channel


:param session_name:


User-specified name that identifies the driver session on the NI gRPC Device Server.

Expand All @@ -74,18 +121,18 @@ GrpcSessionOptions
You can use an empty string if you want to always initialize a new session on the server.
To attach to an existing session, you must specify the session name it was initialized with.



:type session_name: str


:param initialization_behavior:


Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired.

The driver session exists on the NI gRPC Device Server.



:type initialization_behavior: :py:data:`nidigital.SessionInitializationBehavior`
59 changes: 53 additions & 6 deletions docs/nidmm/grpc_session_options.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,53 @@ Support for using NI-DMM over gRPC



Creating a gRPC channel
-----------------------

Using NI-DMM over gRPC requires the ``grpc`` extra::

$ python -m pip install nidmm[grpc]

Every NI-DMM gRPC session is created from a ``grpc.Channel`` that you build and pass to
:py:class:`nidmm.GrpcSessionOptions`. You own the channel, not the session, so you must
close it after the last session using it is closed.

The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is
``create_grpc_device_channel`` from the `nitlsconfig <https://pypi.org/project/nitlsconfig/>`_ package,
which the ``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed
with the NI-DMM runtime and by default will attempt to build an encrypted gRPC channel using mTLS.

Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a
certificate exchange with the remote system.
See `Managing mTLS <https://www.ni.com/docs/en-US/bundle/hardwaremanager/page/mtls-manage.html>`_ for
additional information.

For example::

import nidmm
import nitlsconfig

with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel:
options = nidmm.GrpcSessionOptions(channel, '')
with nidmm.Session('dev1', grpc_options=options) as session:
# Calls to session over the encrypted channel

.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel``
produce an insecure channel.

.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel
arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel
arguments cannot be changed after the channel is built, so they must be supplied here.

.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its
TLS settings from nitlsconfig. See
`Bind Address Support <https://github.com/ni/grpc-device#bind-address-support>`_ and
`NI TLS Config Integration <https://github.com/ni/grpc-device#ni-tls-config-integration>`_ for details.

You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel``
if you need full control over how credentials are supplied.


SessionInitializationBehavior
-----------------------------

Expand Down Expand Up @@ -55,17 +102,17 @@ GrpcSessionOptions


:param grpc_channel:


Specifies the channel to the NI gRPC Device Server.



:type grpc_channel: grpc.Channel


:param session_name:


User-specified name that identifies the driver session on the NI gRPC Device Server.

Expand All @@ -74,18 +121,18 @@ GrpcSessionOptions
You can use an empty string if you want to always initialize a new session on the server.
To attach to an existing session, you must specify the session name it was initialized with.



:type session_name: str


:param initialization_behavior:


Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired.

The driver session exists on the NI gRPC Device Server.



:type initialization_behavior: :py:data:`nidmm.SessionInitializationBehavior`
Loading
Loading