[Issue] Increase specificity of "environment" in azd init/azd up

[savannahostrowski]

Right now, we ask the user to input a name for an environment.

"Environment" is sort of a overloaded term for Python developers. I was chatting with some folks and they thought this meant "please enter your new virtual environment name" and told me that they'd be inclined to enter "venv". They had no clue that Azure had any similar construct.

To avoid confusion, let's add the Azure qualifier to the message so it reads:

Please enter a new Azure environment name:

[vhvb1989]

Savannah Ostrowski (@savannahostrowski) , we can also add an option for help. For example, when prompting for env name:

If user type a question mark ? and enter, we can display a descriptive help message about the input, like:

IMHO, Azure environment can be also confused with this or this

I would probably recommend azd environment if we want to be more descriptive

[savannahostrowski]

Thanks for linking to those other docs. I think this only further emphasizes how loaded the term "environment" is!

I like the first option with the ? but could we have it say [type ? for help] (newbies might be unclear on where to go from here). This option definitely more clear and provides an easy way to learn more. From there, I think we'd want to have the description be something like:

The environment name that will be used to prefix your Azure resources.

I want to be transparent about how this will be used as we scaffold things up for the developer.

Austin Auth (@Austinauth) for some UX input as well.

[Austinauth]

I really like the [type ? for help] idea. It would be nice if you could use it any time you're stuck to get more context. I do have some concerns about seeing it for every input though, I wonder if that will feel overly repetitive?

As far as the messaging goes for this specific example (Azure environment), I was initially confused about the relationship between this input and how it was related to the resource group concept in Azure. I had to confirm with Savannah that they were the same thing.

The environment name that will be used to prefix your Azure resources.

Savannah Ostrowski (@savannahostrowski) I like the helper copy you suggested, one thing I think I am just now realizing is that the environment name is not simply what we will prefix the name of your resource group with, but also all the other resources we make on the user's behalf, is that correct?

The only thing I feel is missing from the helper text (or this step in general) is something that conveys the idea that this specific field is something you (the user) are making up and it can be whatever you want it to be. Versus the next two steps (Location and Subscription), which require a very specific answer from a limited set of pre-existing options.

Does that make sense? Because initially I assumed step 1 behaved like steps 2 and 3. I thought that I needed to input the name of an existing resource group I had already created (similar to selecting an existing Subscription). Maybe this is implied because the step is an input field rather than a choosing an option from a list, but because this is the first step I had no idea the next two would be formatted differently.

[Austinauth]

Building on what you initially suggested Savannah, here are a few tweaks that convey what I'm getting at:

The environment name you provide will be used to prefix your Azure resources.

The environment name you provide will be used to name the Azure resources created as part of this template.

(Is it important to know that it's a prefix?)

I also like Victor Vazquez (@vhvb1989)'s approach to incorporate an example.

The environment name you enter will be used as the name prefix for all of your Azure resources. For example: environment-name-rg or environment-name-keyvault.

[vhvb1989]

The only thing I feel is missing from the helper text (or this step in general) is something that conveys the idea that this specific field is something you (the user) are making up and it can be whatever you want it to be. Versus the next two steps (Location and Subscription), which require a very specific answer from a limited set of pre-existing options.

I think we should change please enter a new environment name for something like please choose and type an environment name (used as suffix for resources provisioned in your Azure subscription):

The other thing I consider important is to give a hint to users about what's the benefit or the general concept behind this environment. Why do we want them to use environments? It is not only a naming strategy for resources. It is a concept for handling the shipping software strategy. As an application developer, I would like to have a development environment where I can play around with test data and experiments. I might want to also have a pre-production environment where I can run regression tests and use for demos. Finally, I would have a production environment for my users/clients.

azd makes it easy to build and set up these tree environments for developers. Each environment would be a published instance of the application. And azd can also help to set up the github repo to automatically run deployments to each environment upon pushing changes to the repo :). So, it's not only about naming resources...

[savannahostrowski]

(used as suffix for resources provisioned in your Azure subscription)

This is what should be shown if they enter ? IMO. I think there's a fine line between too much info and not enough. Let's just make it easy for them to know what they should provide (e.g. not their venv name) and leave more details to the docs (unless we receive additional feedback from users).

This is all an iterative process so we can start small and add if need be.

[ellismg]

I think that Victor Vazquez (@vhvb1989) raises a really good point here - there's nothing that intrinsically ties the name of your environment to any infrastructure - that's something that happens by convention with our templates, because we pass the environment name as an argument to the bicep templates which take it into account when generating names.

But someone could use azd without using that at all.

azd does take a dependency on the environment name with respect to azure resources in one small way, the tool looks for resources with tags of the form azd-env-name to figure out what environment a resource is tied to, but that value is independent of the resource name.

I do think it's best that we think about environments at a level higher than "it is the name for resources" - it's actually much closer to something like a virtual environment or a .env file.

[savannahostrowski]

Yeah - I guess let me articulate this differently...it's not so much "the name for resources" but I've sort of being thinking about the azd environment as a namespace which all of my Azure resources fall within. Would you say that's accurate?

My concern here is that we are introducing the notion of a new type of environment without any details around what it's used for. These details might help developers pick better naming conventions etc.

[ellismg]

I've sort of being thinking about the azd environment as a namespace which all of my Azure resources fall within. Would you say that's accurate?

I guess it depends on if you tie any semantics to the word "namespace". The entire environment concept is something specific to azd and there's no inherent tie between the resources provisioned by azd infa create and an environment (by convention in our templates we add tags to some resources that include this information). The ARM Control Plane itself has on concept of an environment, and you can't in general tell what environment a resource belongs to from the ARM API.

I also struggle with coming up with a clear articulation here. The concept today seems most tied to a configuration of your infrastructure as code file. Each environment can have its owns settings for each parameter for you IaC module. Outputs of the deployment of that infrastructure are stored in the environment that was used to provision it. Looking at Terraform and Pulumi - I think the analog concepts are a workspace and a stack, respectively.

Maybe thinking in terms of what an environment allows you to do (create instances of the infrastructure with different sets of configuration) can help us come up with a better description.

[jongio]

Want to make sure it's not lost that...

1. Our templates use this env name as a prefix for the resource group
2. A dev can create a template that doesn't do # 1

Therefore, the message shouldn't say it's a prefix or suffix.

[weikanglim]

My concern here is that we are introducing the notion of a new type of environment without any details around what it's used for. These details might help developers pick better naming conventions etc

"Environment", while overloaded, is widely known by service developers as a collection of resources that forms the service itself. Here are some examples in the wild: azure docs and azure devop docs. If the user is coming from a Python experience with less development experience with services, I could see the term being confusing, but unfortunately I don't think it's something we can solve given the widely used industry term.

For me, the two issues I see currently that we should improve on:

1. Prompting environment creation on azd init conflicts with my mental model of how service deployment works. When I create my source code repository, I shouldn't be prompted on how I'm going to deploy my service -- I'm not there yet. Solutions:
   i. Delay creation of environment until an action that involves the environment is required (provisioning). This means that .azure files are not going to be created until necessary. When provisioning, it's clear that they have to pick an environment to deploy to.
   ii. Make it clear that we're prompting them to set up a default environment for provisioning later.
2. We need to ease-in the developer on how the "environment name" being prompted for is indeed a deployment environment. I would suggest something providing a concrete example of what environment names look like, and thereby forming the mental link. I would use the naming of the source folder + -dev as a concrete suggestion. This is also most likely the correct naming they want for the dev environment.

Full changes with solutions 1(ii) and 2 applied:

$ ~\repos\todo-app> azd init
Set up an environment for your application to be provisioned and deployed to later.
? Please enter a new environment name (example: todo-app-dev) : 

[ellismg]

I've started to collect some thoughts on this issue in a design note in #196 which tries to describe how environments work today and proposes a new design.

Wei Lim (@weikanglim) - I like your thinking here and it aligns with how I have been thinking about the problem and informed the new design.

[puicchan]

Matt's design note will help to clarify environment in azd context.

I also like Wei's suggestion and don't want the work item to update UX for the CLI to get lost. To summarize, we don't have to mention prefix or suffix, start small and do this:

$ ~\repos\todo-app> azd init -t todo-nodejs-mongo
Set up an environment for your application to be provisioned and deployed to later.
? Please enter a new environment name (example: mytodo-app) :

Austin Auth (@Austinauth)