-
Notifications
You must be signed in to change notification settings - Fork 194
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.
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
Adding docs for working with hooks and azd environment #3949
Conversation
Ideally, the azd environment should be read and used by the script without affecting any other process or the terminal session. See the next code: | ||
|
||
```bash | ||
#!/bin/bash | ||
|
||
declare -A azdEnv | ||
while IFS='=' read -r key value; do | ||
value=$(echo "$value" | sed 's/^"//' | sed 's/"$//') | ||
azdEnv[$key]=$value | ||
done <<EOF | ||
$(azd env get-values) | ||
EOF | ||
|
||
echo "${azdEnv["ENV_VAR_FROM_AZD"]}" | ||
|
||
# just to let you see the output | ||
sleep 5 | ||
``` | ||
|
||
By using `declare -A azdEnv`, you can allocate a set to write the keys and values from the `azd env get-values` output. Then you can access the values by referencing the environment keys with `"${azdEnv["ENV_VAR_FROM_AZD"]}"`. This strategy would allow you to test or run your script either manually or using `azd hooks run <hook name>`, and without affecting the terminal variables. | ||
|
||
Here is the powershell equivalent. | ||
|
||
```pwsh | ||
$azdEnv = @{} | ||
$azdEnvRaw = azd env get-values | ||
|
||
foreach ($line in $azdEnvRaw -split "`n") { | ||
if ($line -match '^(.*?)=(.*)$') { | ||
$key = $matches[1] | ||
$value = $matches[2] -replace '^"|"$' | ||
$azdEnv[$key] = $value | ||
} | ||
} | ||
|
||
Write-Output $azdEnv["ENV_VAR_FROM_AZD"] | ||
|
||
# just to let you see the output | ||
Start-Sleep -Seconds 5 | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I feel like we should be focusing on the automatic behavior of hooks scripts when run in the context of azd
and use auto-injection as a standard and less about how to manually load azd env into the scripts since we already do that.
I'd also like to see examples of how we could make downstream calls from scripts... example - calling python script that will automatically make azd env vars available since they were injected into the script environment.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
100% Agree.
I'm trying to make it explain and recommend the use of azd hooks run ..
for testing and how it is easier to let azd to inject the environment.
There are many templates out there, however, using a load-azd-env script. Some of them exists from before azd hooks run
was available and because folks wanted to test the script whit azd env.
And yes, I am planning to add examples about the downstream calls for python :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Any downstream calls in a sub process will automatically inherit any environment variables already set in the script including azd .env values.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It just feels like all this makes it more confusing when we should just be instructing users to call azd hooks run <hook>
and it will do the right thing.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It just feels like all this makes it more confusing when we should just be instructing users to call azd hooks run and it will do the right thing.
I've been asked a few times, after telling folks to use azd hooks run ...
: - but what if I want to manually run it? (usually for more complex scenarios, like a main script invoking other scripts, where only one of the sub-scripts requires azd-env.
I guess we can elevate the azd hooks run ...
to the learn.microsoft official docs, while leaving this doc as a more advanced/complex guide
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Running azd hooks run <hookname>
will execute whatever script / code is referenced in the hook configuration in the azure.yaml. There isn't any current support to execute arbitrary scripts from with azd.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe this is a separate topic (since I'm writing a different doc), but a common scenario or question I see is developers trying to use the outputs of the main.bicep in their language framework, such as Azure service endpoints. For example, an azd script creates a storage account and an OpenAI account and writes those endpoints out to the azd env file. Next, a node or python app wants to discover and use those endpoints to connect via code. Those languages wouldn't really rely on the azd env file - they have their own env files used by framework packages, or rely on the system/container environment variables. Is there a recommended script somewhere for copying azd env values to a separate .env file for a language framework, or one that writes them out to the system for "permanent" use by the app?
I usually see a hook script used to copy the azd env contents to another location at the end of the provisioning process, but the scenarios in this doc assume the end goal is working with azd environment variables within hook scripts - not outside of them in a language framework/app.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@alexwolfmsft , a common strategy for what you described is to use VSCode tasks settings and the Azure Developer CLI VSCode extension to define a task
for launching your application locally after injecting the azd-env. This is the strategy used by the todo-templates
for running services locally. As you can see, it depends on VSCode and azd-extension.
When no VSCode or when you don't want to define a task.json file, you can create your own script that start your service locally. The script can call azd env list -o json
and parse the output to discovered the default azd environment to use. Then read and use the values to invoke the service. (Basically manually implementing what VSCode does with tasks.json). I think @pamelafox uses this strategy.
And the 100% manual alternative is where folks needs to cd into the service's folder they need to run and figure what env vars to set before manually launching/starting the service. For multiple services, folks would use a new console for each service.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe this is a separate topic (since I'm writing a different doc), but a common scenario or question I see is developers trying to use the outputs of the main.bicep in their language framework, such as Azure service endpoints. For example, an azd script creates a storage account and an OpenAI account and writes those endpoints out to the azd env file. Next, a node or python app wants to discover and use those endpoints to connect via code. Those languages wouldn't really rely on the azd env file - they have their own env files used by framework packages, or rely on the system/container environment variables. Is there a recommended script somewhere for copying azd env values to a separate .env file for a language framework, or one that writes them out to the system for "permanent" use by the app?
I usually see a hook script used to copy the azd env contents to another location at the end of the provisioning process, but the scenarios in this doc assume the end goal is working with azd environment variables within hook scripts - not outside of them in a language framework/app.
@alexwolfmsft - Can you add your scenarios here: #4067
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please have a look at this proposal for azd script run
#4131
Azure Dev CLI Install InstructionsInstall scriptsMacOS/Linux
bash:
pwsh:
WindowsPowerShell install
MSI install
Standalone Binary
MSIDocumentationlearn.microsoft.com documentationtitle: Azure Developer CLI reference
|
#### Use script scoped variables | ||
|
||
Ideally, the azd environment should be read and used by the script without affecting any other process or the terminal session. See the next code: | ||
|
||
```bash | ||
#!/bin/bash | ||
|
||
declare -A azdEnv | ||
while IFS='=' read -r key value; do | ||
value=$(echo "$value" | sed 's/^"//' | sed 's/"$//') | ||
azdEnv[$key]=$value | ||
done <<EOF | ||
$(azd env get-values) | ||
EOF | ||
|
||
echo "${azdEnv["ENV_VAR_FROM_AZD"]}" | ||
|
||
# just to let you see the output | ||
sleep 5 | ||
``` | ||
|
||
By using `declare -A azdEnv`, you can allocate a set to write the keys and values from the `azd env get-values` output. Then you can access the values by referencing the environment keys with `"${azdEnv["ENV_VAR_FROM_AZD"]}"`. This strategy would allow you to test or run your script either manually or using `azd hooks run <hook name>`, and without affecting the terminal variables. | ||
|
||
Here is the powershell equivalent. | ||
|
||
```pwsh | ||
$azdEnv = @{} | ||
$azdEnvRaw = azd env get-values | ||
|
||
foreach ($line in $azdEnvRaw -split "`n") { | ||
if ($line -match '^(.*?)=(.*)$') { | ||
$key = $matches[1] | ||
$value = $matches[2] -replace '^"|"$' | ||
$azdEnv[$key] = $value | ||
} | ||
} | ||
|
||
Write-Output $azdEnv["ENV_VAR_FROM_AZD"] | ||
|
||
# just to let you see the output | ||
Start-Sleep -Seconds 5 | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@alexwolfmsft fyi
No description provided.