Skip to content

Commit 79abec5

Browse files
titom73titom73
authored
doc: Add environment variables documentation (#113)
1 parent a8657c1 commit 79abec5

File tree

5 files changed

+148
-25
lines changed

5 files changed

+148
-25
lines changed

‎docs/usage/cvp.md

+8-6
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,16 @@ Usage: ardl get cvp [OPTIONS]
2121
Download CVP image from Arista server.
2222

2323
Options:
24-
--format TEXT Image format [default: ova]
25-
--output PATH Path to save image [default: .]
24+
--format TEXT Image format [env var: ARISTA_GET_CVP_FORMAT; default: ova]
25+
--output PATH Path to save image [env var: ARISTA_GET_CVP_OUTPUT;
26+
default: .]
2627
--latest Get latest version. If --branch is not use, get the latest
27-
branch with specific release type
28-
--version TEXT EOS version to download
29-
--branch TEXT Branch to download
28+
branch with specific release type [env var:
29+
ARISTA_GET_CVP_LATEST]
30+
--version TEXT EOS version to download [env var: ARISTA_GET_CVP_VERSION]
31+
--branch TEXT Branch to download [env var: ARISTA_GET_CVP_BRANCH]
3032
--dry-run Enable dry-run mode: only run code without system changes
31-
--help Show this message and exit.
33+
--help
3234
```
3335

3436
!!! info

‎docs/usage/environment.md

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Environment Variables in eos-downloader
2+
3+
## Overview
4+
5+
`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:
6+
7+
Standard rule for these variables is:
8+
9+
```bash
10+
# root command
11+
ARISTA_<OPTION_NAME>
12+
13+
# First Level command
14+
ARISTA_<COMMAND_NAME>_<OPTION_NAME>
15+
16+
# Second level command
17+
ARISTA_<COMMAND_NAME>_<COMMAND_NAME>_<OPTION_NAME>
18+
```
19+
20+
!!! TIP "How to get variable names"
21+
Standard _ENV_ variables are exposed in cli help and are visible with `[env var: ARISTA_GET_EOS_DOCKER_TAG]`
22+
23+
## Standard Variables
24+
25+
__Generic Options__:
26+
27+
- __ARISTA_TOKEN__ (`ardl --token`): Load your token and avoid to print your token in clear text during a workflow.
28+
29+
__EOS Options__:
30+
31+
- __ARISTA_GET_EOS_FORMAT__ (`ardl get eos --format`): Image format
32+
- __ARISTA_GET_EOS_OUTPUT__ (`ardl get eos --output`): Path to save EOS image.
33+
- __ARISTA_GET_EOS_VERSION__ (`ardl get eos --version`): Version to download from Arista server
34+
- __ARISTA_GET_EOS_BRANCH__ (`ardl get eos --latest`): Flag to retrieve latest version available from arista server.
35+
- __ARISTA_GET_EOS_BRANCH__ (`ardl get eos --branch`): Branch to download
36+
- __ARISTA_GET_EOS_EVE_NG__ (`ardl get eos --eve-ng`): Run EVE-NG vEOS provisioning (only if CLI runs on an EVE-NG server).
37+
- __ARISTA_GET_EOS_DOCKER_NAME__ (`ardl get eos --docker-name`): Docker image name when importing cEOS.
38+
- __ARISTA_GET_EOS_DOCKER_TAG__ (`ardl get eos --docker-tag`): Docker tag to use when cEOS image is imported in Docker.
39+
- __ARISTA_GET_EOS_RELEASE_TYPE__ (`ardl get eos --release-type`): Release type (M for Maintenance, F for Feature)
40+
41+
__CVP options__:
42+
43+
- __ARISTA_GET_CVP_FORMAT__ (`ardl get cvp --format`): Image format
44+
- __ARISTA_GET_CVP_OUTPUT__ (`ardl get cvp --output`): Path to save CVP image.
45+
- __ARISTA_GET_CVP_LATEST__ (`ardl get cvp --latest`): Flag to retrieve latest version available from arista server.
46+
- __ARISTA_GET_CVP_VERSION__ (`ardl get cvp --version`): Version to download from Arista server
47+
- __ARISTA_GET_CVP_BRANCH__ (`ardl get cvp --branch`): Branch to download
48+
49+
50+
## Usage examples
51+
52+
- Basic usage with `export`
53+
54+
```bash
55+
# Use token from env variables
56+
export ARISTA_TOKEN=1234567890
57+
ardl info versions --branch 4.29
58+
```
59+
60+
- Usage with direnv
61+
62+
```bash
63+
cat .envrc
64+
export ARISTA_TOKEN=1234567890
65+
66+
direnv allow
67+
direnv: loading .envrc
68+
direnv: export +ARISTA_TOKEN
69+
70+
ardl info versions --branch 4.29
71+
```

‎docs/usage/eos.md

+18-12
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ ardl get eos --branch 4.29 --format cEOS --release-type M
1212
# Get a specific version
1313
ardl get eos --version 4.29.4M
1414

15-
# Get a specific version and import to docker using default arista/ceos:{version}{release_type}
15+
# Get a specific version and import to docker
16+
# using default arista/ceos:{version}{release_type}
1617
ardl get eos --version 4.29.4M --import-docker
1718

1819
# Get a specific version and import to EVE-NG
@@ -31,23 +32,28 @@ Usage: ardl get eos [OPTIONS]
3132

3233
Options:
3334
--format TEXT Image format [default: vmdk]
34-
--output PATH Path to save image [default: .]
35+
--output PATH Path to save image [env var: ARISTA_GET_EOS_OUTPUT;
36+
default: .]
3537
--latest Get latest version. If --branch is not use, get the
36-
latest branch with specific release type
38+
latest branch with specific release type [env var:
39+
ARISTA_GET_EOS_LATEST]
3740
--eve-ng Run EVE-NG vEOS provisioning (only if CLI runs on an
38-
EVE-NG server)
39-
--import-docker Import docker image to local docker
41+
EVE-NG server) [env var: ARISTA_GET_EOS_EVE_NG]
42+
--import-docker Import docker image to local docker [env var:
43+
ARISTA_GET_EOS_IMPORT_DOCKER]
4044
--skip-download Skip download process - for debug only
41-
--docker-name TEXT Docker image name [default: arista/ceos]
42-
--docker-tag TEXT Docker image tag
43-
--version TEXT EOS version to download
44-
--release-type TEXT Release type (M for Maintenance, F for Feature)
45-
[default: F]
46-
--branch TEXT Branch to download
45+
--docker-name TEXT Docker image name [env var:
46+
ARISTA_GET_EOS_DOCKER_NAME; default: arista/ceos]
47+
--docker-tag TEXT Docker image tag [env var: ARISTA_GET_EOS_DOCKER_TAG]
48+
--version TEXT EOS version to download [env var:
49+
ARISTA_GET_EOS_VERSION]
50+
--release-type TEXT Release type (M for Maintenance, F for Feature) [env
51+
var: ARISTA_GET_EOS_RELEASE_TYPE; default: F]
52+
--branch TEXT Branch to download [env var: ARISTA_GET_EOS_BRANCH]
4753
--dry-run Enable dry-run mode: only run code without system
4854
changes
4955
--help Show this message and exit.
5056
```
5157
5258
!!! info
53-
You can get information about available version using the [`ardl info version` cli](./info.md)
59+
You can get information about available version using the [`ardl info version` cli](./info.md)

‎eos_downloader/cli/get/commands.py

+50-7
Original file line numberDiff line numberDiff line change
@@ -32,24 +32,28 @@
3232
help="Path to save image",
3333
type=click.Path(),
3434
show_default=True,
35+
show_envvar=True,
3536
)
3637
@click.option(
3738
"--latest",
3839
is_flag=True,
3940
help="Get latest version. If --branch is not use, get the latest branch with specific release type",
4041
default=False,
42+
show_envvar=True,
4143
)
4244
@click.option(
4345
"--eve-ng",
4446
is_flag=True,
4547
help="Run EVE-NG vEOS provisioning (only if CLI runs on an EVE-NG server)",
4648
default=False,
49+
show_envvar=True,
4750
)
4851
@click.option(
4952
"--import-docker",
5053
is_flag=True,
5154
help="Import docker image to local docker",
5255
default=False,
56+
show_envvar=True,
5357
)
5458
@click.option(
5559
"--skip-download",
@@ -58,19 +62,40 @@
5862
default=False,
5963
)
6064
@click.option(
61-
"--docker-name", default="arista/ceos", help="Docker image name", show_default=True
65+
"--docker-name",
66+
default="arista/ceos",
67+
help="Docker image name",
68+
show_default=True,
69+
show_envvar=True,
70+
)
71+
@click.option(
72+
"--docker-tag",
73+
default=None,
74+
help="Docker image tag",
75+
show_default=True,
76+
show_envvar=True,
6277
)
63-
@click.option("--docker-tag", default=None, help="Docker image tag", show_default=True)
6478
@click.option(
65-
"--version", default=None, help="EOS version to download", show_default=True
79+
"--version",
80+
default=None,
81+
help="EOS version to download",
82+
show_default=True,
83+
show_envvar=True,
6684
)
6785
@click.option(
6886
"--release-type",
6987
default=RTYPE_FEATURE,
7088
help="Release type (M for Maintenance, F for Feature)",
7189
show_default=True,
90+
show_envvar=True,
91+
)
92+
@click.option(
93+
"--branch",
94+
default=None,
95+
help="Branch to download",
96+
show_default=True,
97+
show_envvar=True,
7298
)
73-
@click.option("--branch", default=None, help="Branch to download", show_default=True)
7499
@click.option(
75100
"--dry-run",
76101
is_flag=True,
@@ -135,24 +160,42 @@ def eos(
135160

136161

137162
@click.command()
138-
@click.option("--format", default="ova", help="Image format", show_default=True)
163+
@click.option(
164+
"--format",
165+
default="ova",
166+
help="Image format",
167+
show_default=True,
168+
show_envvar=True,
169+
)
139170
@click.option(
140171
"--output",
141172
default=str(os.path.relpath(os.getcwd(), start=os.curdir)),
142173
help="Path to save image",
143174
type=click.Path(),
144175
show_default=True,
176+
show_envvar=True,
145177
)
146178
@click.option(
147179
"--latest",
148180
is_flag=True,
149181
help="Get latest version. If --branch is not use, get the latest branch with specific release type",
150182
default=False,
183+
show_envvar=True,
151184
)
152185
@click.option(
153-
"--version", default=None, help="EOS version to download", show_default=True
186+
"--version",
187+
default=None,
188+
help="EOS version to download",
189+
show_default=True,
190+
show_envvar=True,
191+
)
192+
@click.option(
193+
"--branch",
194+
default=None,
195+
help="Branch to download",
196+
show_default=True,
197+
show_envvar=True,
154198
)
155-
@click.option("--branch", default=None, help="Branch to download", show_default=True)
156199
@click.option(
157200
"--dry-run",
158201
is_flag=True,

‎mkdocs.yml

+1
Original file line numberDiff line numberDiff line change
@@ -164,6 +164,7 @@ nav:
164164
- Usage:
165165
- Get EOS package: usage/eos.md
166166
- Get CVP package: usage/cvp.md
167+
- Environment variables: usage/environment.md
167168
- Version information: usage/info.md
168169
- Software mapping: usage/mapping.md
169170
- Code documentation:

0 commit comments

Comments
 (0)