doc: Add environment variables documentation (#113)

titom73 · Dec 15, 2024 · 79abec5 · 79abec5
1 parent a8657c1
commit 79abec5
Show file tree

Hide file tree

Showing 5 changed files with 148 additions and 25 deletions.
diff --git a/docs/usage/cvp.md b/docs/usage/cvp.md
@@ -21,14 +21,16 @@ Usage: ardl get cvp [OPTIONS]
   Download CVP image from Arista server.
 
 Options:
-  --format TEXT   Image format  [default: ova]
-  --output PATH   Path to save image  [default: .]
+  --format TEXT   Image format  [env var: ARISTA_GET_CVP_FORMAT; default: ova]
+  --output PATH   Path to save image  [env var: ARISTA_GET_CVP_OUTPUT;
+                  default: .]
   --latest        Get latest version. If --branch is not use, get the latest
-                  branch with specific release type
-  --version TEXT  EOS version to download
-  --branch TEXT   Branch to download
+                  branch with specific release type  [env var:
+                  ARISTA_GET_CVP_LATEST]
+  --version TEXT  EOS version to download  [env var: ARISTA_GET_CVP_VERSION]
+  --branch TEXT   Branch to download  [env var: ARISTA_GET_CVP_BRANCH]
   --dry-run       Enable dry-run mode: only run code without system changes
-  --help          Show this message and exit.
+  --help
 ```
 
 !!! info

diff --git a/docs/usage/environment.md b/docs/usage/environment.md
@@ -0,0 +1,71 @@
+# Environment Variables in eos-downloader
+
+## Overview
+
+`ardl` is able to read environment variables to replace cli option to make it easier to work with in workflow. Even if all cli options can be replaced by environment variables, here are the most useful ones:
+
+Standard rule for these variables is:
+
+```bash
+# root command
+ARISTA_<OPTION_NAME>
+
+# First Level command
+ARISTA_<COMMAND_NAME>_<OPTION_NAME>
+
+# Second level command
+ARISTA_<COMMAND_NAME>_<COMMAND_NAME>_<OPTION_NAME>
+```
+
+!!! TIP "How to get variable names"
+    Standard _ENV_ variables are exposed in cli help and are visible with `[env var: ARISTA_GET_EOS_DOCKER_TAG]`
+
+## Standard Variables
+
+__Generic Options__:
+
+- __ARISTA_TOKEN__ (`ardl --token`): Load your token and avoid to print your token in clear text during a workflow.
+
+__EOS Options__:
+
+- __ARISTA_GET_EOS_FORMAT__ (`ardl get eos --format`): Image format
+- __ARISTA_GET_EOS_OUTPUT__ (`ardl get eos --output`): Path to save EOS image.
+- __ARISTA_GET_EOS_VERSION__ (`ardl get eos --version`): Version to download from Arista server
+- __ARISTA_GET_EOS_BRANCH__ (`ardl get eos --latest`): Flag to retrieve latest version available from arista server.
+- __ARISTA_GET_EOS_BRANCH__ (`ardl get eos --branch`): Branch to download
+- __ARISTA_GET_EOS_EVE_NG__ (`ardl get eos --eve-ng`): Run EVE-NG vEOS provisioning (only if CLI runs on an EVE-NG server).
+- __ARISTA_GET_EOS_DOCKER_NAME__ (`ardl get eos --docker-name`): Docker image name when importing cEOS.
+- __ARISTA_GET_EOS_DOCKER_TAG__ (`ardl get eos --docker-tag`): Docker tag to use when cEOS image is imported in Docker.
+- __ARISTA_GET_EOS_RELEASE_TYPE__ (`ardl get eos --release-type`): Release type (M for Maintenance, F for Feature)
+
+__CVP options__:
+
+- __ARISTA_GET_CVP_FORMAT__ (`ardl get cvp --format`): Image format
+- __ARISTA_GET_CVP_OUTPUT__ (`ardl get cvp --output`): Path to save CVP image.
+- __ARISTA_GET_CVP_LATEST__ (`ardl get cvp --latest`): Flag to retrieve latest version available from arista server.
+- __ARISTA_GET_CVP_VERSION__ (`ardl get cvp --version`): Version to download from Arista server
+- __ARISTA_GET_CVP_BRANCH__ (`ardl get cvp --branch`): Branch to download
+
+
+## Usage examples
+
+- Basic usage with `export`
+
+```bash
+# Use token from env variables
+export ARISTA_TOKEN=1234567890
+ardl info versions --branch 4.29
+```
+
+- Usage with direnv
+
+```bash
+cat .envrc
+export ARISTA_TOKEN=1234567890
+
+direnv allow
+direnv: loading .envrc
+direnv: export +ARISTA_TOKEN
+
+ardl info versions --branch 4.29
+```
diff --git a/docs/usage/eos.md b/docs/usage/eos.md
@@ -12,7 +12,8 @@ ardl get eos --branch 4.29 --format cEOS --release-type M
 # Get a specific version
 ardl get eos --version 4.29.4M
 
-# Get a specific version and import to docker using default arista/ceos:{version}{release_type}
+# Get a specific version and import to docker
+# using default arista/ceos:{version}{release_type}
 ardl get eos --version 4.29.4M --import-docker
 
 # Get a specific version and import to EVE-NG
@@ -31,23 +32,28 @@ Usage: ardl get eos [OPTIONS]
 
 Options:
   --format TEXT        Image format  [default: vmdk]
-  --output PATH        Path to save image  [default: .]
+  --output PATH        Path to save image  [env var: ARISTA_GET_EOS_OUTPUT;
+                       default: .]
   --latest             Get latest version. If --branch is not use, get the
-                       latest branch with specific release type
+                       latest branch with specific release type  [env var:
+                       ARISTA_GET_EOS_LATEST]
   --eve-ng             Run EVE-NG vEOS provisioning (only if CLI runs on an
-                       EVE-NG server)
-  --import-docker      Import docker image to local docker
+                       EVE-NG server)  [env var: ARISTA_GET_EOS_EVE_NG]
+  --import-docker      Import docker image to local docker  [env var:
+                       ARISTA_GET_EOS_IMPORT_DOCKER]
   --skip-download      Skip download process - for debug only
-  --docker-name TEXT   Docker image name  [default: arista/ceos]
-  --docker-tag TEXT    Docker image tag
-  --version TEXT       EOS version to download
-  --release-type TEXT  Release type (M for Maintenance, F for Feature)
-                       [default: F]
-  --branch TEXT        Branch to download
+  --docker-name TEXT   Docker image name  [env var:
+                       ARISTA_GET_EOS_DOCKER_NAME; default: arista/ceos]
+  --docker-tag TEXT    Docker image tag  [env var: ARISTA_GET_EOS_DOCKER_TAG]
+  --version TEXT       EOS version to download  [env var:
+                       ARISTA_GET_EOS_VERSION]
+  --release-type TEXT  Release type (M for Maintenance, F for Feature)  [env
+                       var: ARISTA_GET_EOS_RELEASE_TYPE; default: F]
+  --branch TEXT        Branch to download  [env var: ARISTA_GET_EOS_BRANCH]
   --dry-run            Enable dry-run mode: only run code without system
                        changes
   --help               Show this message and exit.
 ```
 
 !!! info
-    You can get information about available version using the [`ardl info version` cli](./info.md)
+    You can get information about available version using the [`ardl info version` cli](./info.md)
diff --git a/eos_downloader/cli/get/commands.py b/eos_downloader/cli/get/commands.py
@@ -32,24 +32,28 @@
     help="Path to save image",
     type=click.Path(),
     show_default=True,
+    show_envvar=True,
 )
 @click.option(
     "--latest",
     is_flag=True,
     help="Get latest version. If --branch is not use, get the latest branch with specific release type",
     default=False,
+    show_envvar=True,
 )
 @click.option(
     "--eve-ng",
     is_flag=True,
     help="Run EVE-NG vEOS provisioning (only if CLI runs on an EVE-NG server)",
     default=False,
+    show_envvar=True,
 )
 @click.option(
     "--import-docker",
     is_flag=True,
     help="Import docker image to local docker",
     default=False,
+    show_envvar=True,
 )
 @click.option(
     "--skip-download",
@@ -58,19 +62,40 @@
     default=False,
 )
 @click.option(
-    "--docker-name", default="arista/ceos", help="Docker image name", show_default=True
+    "--docker-name",
+    default="arista/ceos",
+    help="Docker image name",
+    show_default=True,
+    show_envvar=True,
+)
+@click.option(
+    "--docker-tag",
+    default=None,
+    help="Docker image tag",
+    show_default=True,
+    show_envvar=True,
 )
-@click.option("--docker-tag", default=None, help="Docker image tag", show_default=True)
 @click.option(
-    "--version", default=None, help="EOS version to download", show_default=True
+    "--version",
+    default=None,
+    help="EOS version to download",
+    show_default=True,
+    show_envvar=True,
 )
 @click.option(
     "--release-type",
     default=RTYPE_FEATURE,
     help="Release type (M for Maintenance, F for Feature)",
     show_default=True,
+    show_envvar=True,
+)
+@click.option(
+    "--branch",
+    default=None,
+    help="Branch to download",
+    show_default=True,
+    show_envvar=True,
 )
-@click.option("--branch", default=None, help="Branch to download", show_default=True)
 @click.option(
     "--dry-run",
     is_flag=True,
@@ -135,24 +160,42 @@ def eos(
 
 
 @click.command()
-@click.option("--format", default="ova", help="Image format", show_default=True)
+@click.option(
+    "--format",
+    default="ova",
+    help="Image format",
+    show_default=True,
+    show_envvar=True,
+)
 @click.option(
     "--output",
     default=str(os.path.relpath(os.getcwd(), start=os.curdir)),
     help="Path to save image",
     type=click.Path(),
     show_default=True,
+    show_envvar=True,
 )
 @click.option(
     "--latest",
     is_flag=True,
     help="Get latest version. If --branch is not use, get the latest branch with specific release type",
     default=False,
+    show_envvar=True,
 )
 @click.option(
-    "--version", default=None, help="EOS version to download", show_default=True
+    "--version",
+    default=None,
+    help="EOS version to download",
+    show_default=True,
+    show_envvar=True,
+)
+@click.option(
+    "--branch",
+    default=None,
+    help="Branch to download",
+    show_default=True,
+    show_envvar=True,
 )
-@click.option("--branch", default=None, help="Branch to download", show_default=True)
 @click.option(
     "--dry-run",
     is_flag=True,

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -164,6 +164,7 @@ nav:
   - Usage:
       - Get EOS package: usage/eos.md
       - Get CVP package: usage/cvp.md
+      - Environment variables: usage/environment.md
       - Version information: usage/info.md
       - Software mapping: usage/mapping.md
   - Code documentation: