Clarify dev environment usage in docs (azimuth-cloud#162)

* Clarify dev environment usage in docs

* Add tip for producing unique values

Author: Matt Pryor

docs/developing/index.md

@@ -4,58 +4,52 @@ An Azimuth deployment consists of several interdependent components, some of whi
 Azimuth-specific and some of which are third-party components. Plugging code under
 development into such a system can be tricky, making development difficult and slow.
 
-## Developing Azimuth components
-
-Azimuth has a number of components, mostly written in Python:
+## Deploying a dev instance
 
-  * [Azimuth API and UI](https://github.com/stackhpc/azimuth) - user-facing API and UI
-  * [Azimuth CaaS operator](https://github.com/stackhpc/azimuth-caas-operator) - Kubernetes operator implementing CaaS functionality
-  * [Azimuth CAPI operator](https://github.com/stackhpc/azimuth-capi-operator) - Kubernetes operator implementing Kubernetes and Kubernetes App functionality
-  * [Azimuth identity operator](https://github.com/stackhpc/azimuth-identity-operator) - Kubernetes operator implementing platform identity
-  * [Zenith](https://github.com/stackhpc/zenith) - secure, tunnelling application proxy used to expose platform services
-  * [Cluster API addon provider](https://github.com/stackhpc/cluster-api-addon-provider) - addons for Cluster API clusters
-  * [Cluster API janitor for OpenStack](https://github.com/stackhpc/cluster-api-janitor-openstack) - resource cleanup for Cluster API clusters on OpenStack clouds
+In order to develop Azimuth, you first need a running Azimuth instance.
 
-It is useful to develop these components in the context of a running Azimuth installation,
-as they have dependencies on each other.
+Each developer should have their own independent instance of Azimuth for development,
+as during development they will make changes to the running Azimuth components that may
+conflict with or break things for others.
 
-To enable this, Azimuth uses [Tilt](https://tilt.dev/) to provide a developer environment
-where code under development is automatically built and injected into a live system that
-you can interact with. Tilt provides a dashboard that can be used to drill down into
-build failures and the logs of the components under development.
+### Creating a dev environment
 
-![Azimuth in Tilt](tilt-interface.png)
+Azimuth supports using a single [configuration environment](../environments.md) to deploy multiple
+independent Azimuth instances. When
+[activating an environment](../deployment/#activating-an-environment), a unique instance name
+can be given as a second argument to the `activate` script, e.g.:
 
-### Prerequisites
-
-In order to use Tilt to develop Azimuth, the following tools must be available on your
-development machine (in addition to those required to install Azimuth itself):
-
-  * The [Tilt CLI](https://docs.tilt.dev/install.html)
-  * A `docker` command, e.g. [Docker Desktop](https://docs.docker.com/desktop/)
-  * The [kubectl command](https://kubernetes.io/docs/tasks/tools/#kubectl)
-  * The [Helm CLI](https://helm.sh/docs/intro/install/)
+```bash
+# Activating an environment with a unique instance name
+source ./bin/activate my-environment jbloggs
+```
 
-For developing the Azimuth UI, the following are also required:
+In order for an environment to be used in this way, it must be specially prepared to be more
+dynamic than an environment that you would use for staging or production. In particular, only
+[single node deployments](../configuration/02-deployment-method.md#single-node) are usable in
+this way, as HA deployments do not support dynamically allocating a floating IP for the ingress
+controller.
 
-  * [node.js](https://nodejs.org)
-  * The [Yarn Classic](https://classic.yarnpkg.com/lang/en/docs/install/) package manager
+It is recommended that you create an environment in your Azimuth configuration repository
+for doing Azimuth development on your cloud. This environment should include any site-specific
+customisations that are required, usually by building on a
+[site mixin](../environments.md#using-mixin-environments). The
+[demo environment](https://github.com/stackhpc/azimuth-config/tree/devel/environments/demo)
+is a good starting point for this, as it is designed to be flexible and dynamic.
 
-### Deploying a dev instance
+!!! tip  "Producing unique values in your Azimuth configuration"
 
-To use Tilt for developing Azimuth components, you first need a running Azimuth instance.
-    
-Each developer should have their own independent instance of Azimuth as Tilt will make
-changes to the running Azimuth components, based on the code under development, that may
-disrupt or break things for others.
+    The Ansible variable `azimuth_environment` contains the unique instance name, and
+    can be used in other variables in your configuration where a unique value is required
+    for each developer environment.
 
-!!! tip
+!!! warning  "Developers should use their own application credential"
 
-    A single node deployment, e.g. a [demo deployment](../try.md), is sufficient for developing
-    the Azimuth components.
+    You should not include an application credential in your development environment.
+    Instead, each developer can use their own application credential as described in the
+    next section.
 
-    You may wish to maintain a [development environment](../environments.md) containing
-    site-specific customisations.
+### Using the dev environment
 
 The following instructions assume that your Azimuth configuration contains a developer environment
 called `dev`. It is assumed that you have your Azimuth configuration checked out and that you have
@@ -81,6 +75,44 @@ ansible-galaxy install -f -r requirements.yml
 ansible-playbook stackhpc.azimuth_ops.provision
 ```
 
+## Developing Azimuth components
+
+Azimuth has a number of components, mostly written in Python:
+
+  * [Azimuth API and UI](https://github.com/stackhpc/azimuth) - user-facing API and UI
+  * [Azimuth CaaS operator](https://github.com/stackhpc/azimuth-caas-operator) - Kubernetes operator implementing CaaS functionality
+  * [Azimuth CAPI operator](https://github.com/stackhpc/azimuth-capi-operator) - Kubernetes operator implementing Kubernetes and Kubernetes App functionality
+  * [Azimuth identity operator](https://github.com/stackhpc/azimuth-identity-operator) - Kubernetes operator implementing platform identity
+  * [Azimuth schedule operator](https://github.com/stackhpc/azimuth-schedule-operator) - Kubernetes operator implementing platform scheduling
+  * [Zenith](https://github.com/stackhpc/zenith) - secure, tunnelling application proxy used to expose platform services
+  * [Cluster API addon provider](https://github.com/stackhpc/cluster-api-addon-provider) - addons for Cluster API clusters
+  * [Cluster API janitor for OpenStack](https://github.com/stackhpc/cluster-api-janitor-openstack) - resource cleanup for Cluster API clusters on OpenStack clouds
+
+It is useful to develop these components in the context of a running Azimuth installation,
+as they have dependencies on each other.
+
+To enable this, Azimuth uses [Tilt](https://tilt.dev/) to provide a developer environment
+where code under development is automatically built and injected into a live system that
+you can interact with. Tilt provides a dashboard that can be used to drill down into
+build failures and the logs of the components under development.
+
+![Azimuth in Tilt](tilt-interface.png)
+
+### Prerequisites
+
+In order to use Tilt to develop Azimuth, the following tools must be available on your
+development machine (in addition to those required to install Azimuth itself):
+
+  * The [Tilt CLI](https://docs.tilt.dev/install.html)
+  * A `docker` command, e.g. [Docker Desktop](https://docs.docker.com/desktop/)
+  * The [kubectl command](https://kubernetes.io/docs/tasks/tools/#kubectl)
+  * The [Helm CLI](https://helm.sh/docs/intro/install/)
+
+For developing the Azimuth UI, the following are also required:
+
+  * [node.js](https://nodejs.org)
+  * The [Yarn Classic](https://classic.yarnpkg.com/lang/en/docs/install/) package manager
+
 ### Configuring a container registry
 
 Azimuth's Tilt configuration looks for a file called `tilt-settings.yaml` that defines settings