Skip to content

Commit

Permalink
secrets docs (#14951)
Browse files Browse the repository at this point in the history 
* secrets docs

* Update docs/source-app/glossary/secrets.rst

Co-authored-by: Yurij Mikhalevich <yurij@grid.ai>

* Apply suggestions from code review

Co-authored-by: Adrian Wälchli <aedu.waelchli@gmail.com>

* Update secrets.rst

* links

Co-authored-by: Yurij Mikhalevich <yurij@grid.ai>
Co-authored-by: Jirka Borovec <Borda@users.noreply.github.com>
Co-authored-by: Adrian Wälchli <aedu.waelchli@gmail.com>
Co-authored-by: Jirka <jirka.borovec@seznam.cz>
  • Loading branch information
@edenlightning @yurijmikhalevich
@Borda @awaelchli
5 people committed Oct 11, 2022
1 parent c1db77e commit 8715cd0
Show file tree
Hide file tree
Showing 3 changed files with 39 additions and 62 deletions.
97 changes: 35 additions & 62 deletions docs/source-app/glossary/secrets.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,55 +4,56 @@
Encrypted Secrets
#################

Is your App using data or values (for example: API keys or access credentials) that you don't want to expose in your App code? If the answer is yes, you'll want to use Secrets. Secrets are encrypted values that are stored in the Lightning.ai database and are decrypted at runtime.
Encrypted Secrets allow you to pass private data to your apps, like API keys, access tokens, database passwords, or other credentials, in a secure way without exposing them in your code.
Secrets provide you with a secure way to store this data in a way that is accessible to Apps so that they can authenticate third-party services/solutions.

.. tip::
For non-sensitive configuration values, we recommend using :ref:`plain-text Environment Variables <environment_variables>`.

***************
What did we do?
***************
************
Add a secret
************

When a Lightning App (App) **runs in the cloud**, a Secret can be exposed to the App using environment variables.
The value of the Secret is encrypted in the Lightning.ai database, and is only decrypted and accessible to
LightningFlow (Flow) or LightningWork (Work) processes in the cloud (when you use the ``--cloud`` option running your App).
Add the secret to your profile on lightning.ai.
Log in to your lightning.ai account > **Profile** > **Secrets** tab > click the **+New** button.
Provide a name and value to your secret, for example, name could be "github_api_token".

----

**********************
What were we thinking?
**********************
.. note::
Secret names must start with a letter and can only contain letters, numbers, dashes, and periods. The Secret names must comply with `RFC1123 naming conventions <https://www.rfc-editor.org/rfc/rfc1123>`_. The Secret value has no restrictions.

Many Apps require access to private data like API keys, access tokens, database passwords, or other credentials. You need to protect this data.
We developed this feature to provide you with a secure way to store this data in a way that is accessible to Apps so that they can authenticate third-party services/solutions.
.. raw:: html

----
<br />
<video id="background-video" autoplay loop muted controls poster="https://pl-flash-data.s3.amazonaws.com/assets_lightning/docs/images/storage/encrypted_secrets_login.png" width="100%">
<source src="https://pl-flash-data.s3.amazonaws.com/assets_lightning/docs/images/storage/encrypted_secrets_login.mp4" type="video/mp4" width="100%">
</video>
<br />
<br />

*********************
Use Encrypted Secrets
*********************
************
Use a secret
************

To use Encrypted Secrets:
1. Add an environment variable to your app to read the secret. For example, add an "api_token" environment variable:

#. Log in to your lightning.ai account, go to **Secrets**, and create the Secret (provide a name and value for the secret).
.. code:: python
.. note:: Once you create a Secret, you can bind it to any of your Apps. You do not need to create a new Secret for each App if the Secret value is the same.
import os
#. Prepare an environment variable to use with the Secret in your App.
component.connect(api_token=os.environ["api_token"])
#. Use the following command to add the Secret to your App:
2. Pass the secret to your app run with the following command:

.. code:: bash
lightning run app app.py --cloud --secret <environment-variable>=<secret-name>
The environment variables are available in all Flows and Works, and can be accessed as follows:
In this example, the command would be:

.. code:: python
.. code:: bash
import os
lightning run app app.py --cloud --secret api_token=github_api_token
print(os.environ["<environment-variable>"])
The ``--secret`` option can be used for multiple Secrets, and alongside the ``--env`` option.

Expand All @@ -62,41 +63,13 @@ Here's an example:
lightning run app app.py --cloud --env FOO=bar --secret MY_APP_SECRET=my-secret --secret ANOTHER_SECRET=another-secret
----

Example
^^^^^^^
The best way to show you how to use Encrypted Secrets is with an example.

First, log in to your `lightning.ai account <https://lightning.ai/>`_ and create a Secret.

.. raw:: html

<br />
<video id="background-video" autoplay loop muted controls poster="https://pl-flash-data.s3.amazonaws.com/assets_lightning/docs/images/storage/encrypted_secrets_login.png" width="100%">
<source src="https://pl-flash-data.s3.amazonaws.com/assets_lightning/docs/images/storage/encrypted_secrets_login.mp4" type="video/mp4" width="100%">
</video>
<br />
<br />

.. note::
Secret names must start with a letter and can only contain letters, numbers, dashes, and periods. The Secret names must comply with `RFC1123 naming conventions <https://www.rfc-editor.org/rfc/rfc1123>`_. The Secret value has no restrictions.

After creating a Secret named ``my-secret`` with the value ``some-secret-value`` we'll bind it to the environment variable ``MY_APP_SECRET`` within our App. The binding is accomplished by using the ``--secret`` option when running the App from the Lightning CLI.

The ``--secret``` option works similar to ``--env``, but instead of providing a value, you provide the name of the Secret that is replaced with with the value that you want to bind to the environment variable:

.. code:: bash
lightning run app app.py --cloud --secret MY_APP_SECRET=my-secret
The environment variables are available in all Flows and Works, and can be accessed as follows:

.. code:: python
import os
----

print(os.environ["MY_APP_SECRET"])
******************
How does this work
******************

This code prints out ``some-secret-value``.
When a Lightning App (App) **runs in the cloud**, a Secret can be exposed to the App using environment variables.
The value of the Secret is encrypted in the Lightning.ai database, and is only decrypted and accessible to
LightningFlow (Flow) or LightningWork (Work) processes in the cloud (when you use the ``--cloud`` option running your App).
2 changes: 2 additions & 0 deletions docs/source-app/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,7 @@ Keep Learning
Access the App State <workflows/access_app_state/access_app_state>
Add a web user interface (UI) <workflows/add_web_ui/index>
Add a web link <workflows/add_web_link>
Add encrypted secrets <glossary/secrets>
Arrange app tabs <workflows/arrange_tabs/index>
Develop a Command Line Interface (CLI) <workflows/build_command_line_interface/index>
Develop a Lightning App <workflows/build_lightning_app/index>
Expand All @@ -231,6 +232,7 @@ Keep Learning
Run an App on the cloud <workflows/run_app_on_cloud/index>
Run Apps on your cloud account (BYOC) <workflows/byoc/index>
Run work in parallel <workflows/run_work_in_parallel>
Save files <glossary/storage/drive.rst>
Share an app <workflows/share_app>
Share files between components <workflows/share_files_between_components>

Expand Down
2 changes: 2 additions & 0 deletions docs/source-lit/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ Welcome to ⚡ Lightning Apps
Access the App State <workflows/access_app_state/access_app_state>
Add a web user interface (UI) <workflows/add_web_ui/index>
Add a web link <workflows/add_web_link>
Add encrypted secrets <glossary/secrets>
Arrange app tabs <workflows/arrange_tabs/index>
Develop a Lightning App <workflows/build_lightning_app/index>
Develop a Lightning Component <workflows/build_lightning_component/index>
Expand All @@ -75,6 +76,7 @@ Welcome to ⚡ Lightning Apps
Run an App on the cloud <workflows/run_app_on_cloud/index>
Run Apps on your cloud account (BYOC) <workflows/byoc/index>
Run work in parallel <workflows/run_work_in_parallel>
Save files <glossary/storage/drive.rst>
Share an app <workflows/share_app>
Share files between components <workflows/share_files_between_components>

Expand Down

0 comments on commit 8715cd0

Please sign in to comment.